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How  this  Manual  is 
Structured 

Tutorial 

User’s  Guide 

Reference 

\ 

Further  Reading 


Preface 


This  manual  is  addressed  to  anyone  who  is  interested  in  writing  SunView  pro¬ 
grams.  It  assumes  that  the  reader  understands  the  C  programming  language. 
Before  you  begin  to  write  your  own  programs,  read  the  SunView  1  Beginner’s 
Guide  and  spend  some  time  using  the  SunView  environment  to  become  familiar 
with  the  tools  and  demonstration  programs  provided  with  SunView.^ 

By  convention,  manuals  fall  into  three  categories.  Tutorial,  User’s  Guide,  and 
Reference.  This  manual  is  a  combination  of  all  three. 

Chapter  4,  Using  Windows,  serves  as  a  tutorial  introduction  to  SunView.  As  you 
read  and  type  in  and  finally  modify  its  examples,  you  will  be  writing  simple  Sun¬ 
View  programs  in  the  proverbial  “10  minutes  to  SunView”  time  frame.  You  can 
then  read  the  later  chapters  when  you  need  to  incorporate  the  features  they 
describe  into  your  programs. 

This  entire  manual  is  the  user’s  guide.  Start  at  the  beginning,  keep  reading,  and 
you  win  understand  the  SunView  model,  how  SunView  programs  woik,  and  how 
to  create  and  use  all  the  different  SunView  objects  in  your  own  window  pro¬ 
grams. 

Chapter  19,  SunView  Interface  Summary,  lists  aH  the  attributes  of  the  different 
SunView  objects  and  packages,  and  the  functions  and  macros  to  operate  on  them. 
Because  of  the  nature  of  SunView  and  its  use  of  an  attribute  value  interface,  it 
uses  a  few  simple  calls  with  many  attributes  for  them.  Hence  in  practice  this  is 
aU  the  reference  section  you  wiU  need  on  a  day-to-day  basis. 

This  manual  does  not  teach  you  how  the  SunView  window  system  itself  works, 
only  how  to  make  working  SunView  applications.  The  former  is  covered,  along 
with  many  low-level,  esoteric,  and  complex  details,  in  the  SunView  System 
Programmer’s  Guide. 


^  These  tools  and  dononstration  programs  are  optional  software.  They  may  not  be  installed  on  your  system. 
Consult  Installing  the  SunOS  for  more  details. 
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Format  of  Chapters 


Lists,  Summaries,  and  the  Index 


The  chapters  which  explain  the  various  SunView  packages  have  a  common  for¬ 
mat.  Each  chapter’s  first  page  usually  mentions 

o  what  the  package  does 

□  existing  SunView  programs  you  can  run  to  see  the  package  in  action 

□  header  files  you  must  include  to  use  the  package 

□  what  the  “summary  tables”  for  the  package  are,  and  on  what  pages  they  start 
in  Chapter  19,  SunView  Interface  Summary. 


The  second  page  of  most  of  the  chapters  on  packages  has  a  list  of  the  attributes 
and  functions  the  package  provides.  This  information  doesn’t  teU  you  what  you 
need  to  know  to  use  the  package;  rather,  it  is  intended  to  give  you  a  feel  for  what 
you  can  do  with  the  package.  When  you  are  more  familiar  with  a  package,  you 
can  go  straight  to  its  summary  tables  in  Chapter  19  to  quickly  find  out  how  to  use 
some  attribute  or  function.  However,  there  may  be  tricks  or  nuances  involved  in 
using  the  package  which  are  only  covered  in  the  chapters.  You  should  consult 
the  Index  before  using  any  attribute  or  function  that  you  are  not  familiar  with. 
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Introduction 


What  is  SunView? 


SunView  (Sun  Visual/Ihtegrated  Environment  for  Woricstations)  is  a  user- 
interface  toolkit  to  support  interactive,  graphics-based  applications  running 
within  windows.  It  consists  of  two  major  areas  of  functionality:  building  blocks 
for  output,  and  a  run-time  system  for  managing  input.  The  building  blocks 
include  four  types  of  windows: 

□  canvases  on  which  programs  can  draw, 

□  text  subwindows  with  built  in  editing  capabilities, 

□  panels  containing  items  such  as  buttons,  choice  items,  and  analog  sliders, 
o  tty  subwindows  in  which  programs  can  be  run. 

Canvases,  text  subwindows,  and  panels  can  be  scrolled. 

These  windows  are  arranged  as  subwindows  within  frames,  which  are  themselves 
windows.  Frames  can  be  transitory  or  permanent. 

Transient  interactions  with  the  user  can  also  take  place  in  menus  which  can 
“pop-up”  anywhere  on  the  screen,  and  in  alerts. 

The  run-time  system  is  based  on  a  central  Notifier  in  each  application  which  dis¬ 
tributes  input  to  the  appropriate  window,  and  a  window  manager  which  manages 
overlapping  windows,  distributing  to  the  appropriate  application. 

The  exchange  of  data  between  applications  running  in  separate  windows  (in  the 
same  or  separate  processes)  is  facilitated  by  a  Selection  Service. 

The  Sun  implementations  of  graphics  standards  —  CGI,  CORE,  GKS  —  include 
extensions  to  mn  within  windows.  See  the  SunCGI  Reference  Manual,  the  Sun- 
Core  Reference  Manual,  and  the  SunGKS  manual,  respectively,  for  more  infor¬ 
mation. 
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History 


Release  3.0 


Release  3.2 


SunView  first  appeared  in  SunOS  Release  3.0.  It  is  an  extension  and  refinement 
of  SunWindows  2.0,  containing  many  enhancements,  bug  fixes  and  new  facilities 
not  present  in  SunWindows.  SunView  is  upward  compatible  with  SunWindows 
—  applications  originally  written  under  2.0  can  be  recompiled  and  run  under 
SunView. 

In  Release  3.0,  these  changes  were  reflected  in  a  new  organization  for  the  Sun¬ 
View  documentation.  The  material  on  Pixrects  from  the  2.0  SunWindows  Refer¬ 
ence  Manual  was  broken  out  into  a  separate  document,  the  Pixrect  Reference 
Manual.  Two  new  documents  were  introduced,  the  SunView  Programmer’s 
Guide  and  the  SunView  System  Programmer’s  Guide. 

The  basic  SunView  interface,  intended  to  meet  the  needs  of  simple  and 
moderately  complex  applications,  is  documented  here.  This  basic  interface  cov¬ 
ers  the  functionality  of  the  SunWindows  window  and  tool  layers. 

The  companion  to  this  document  is  the  SunView  System  Programmer’ s  Guide. 

Its  contents  are  a  combination  of  new  and  old  material.  Several  of  its  chapters 
document  new  facilities  such  as  the  Notifier,  the  Selection  Service  and  the 
Defaults  Package.  Also  included  is  material  from  the  old  SunWindows  Rrference 
Manual  which  is  of  interest  to  implementors  of  window  managers  and  other 
advanced  applications,  such  as  the  window  manager  routines. 


Many  bug  fixes  and  performance  improvements  were  made  to  SunView  for 
Release  3.2.  This  guide  was  extensively  revised  and  added  to  for  Release  3.2. 


Release  3.4  Further  bug  fixes  and  enhancements  came  out  with  Release  3.4.  These  were 

documented  in  the  Release  3.4  Manual. 


Release  3.5  Release  3.5  brought  support  for  hardware  double-buffering  under  SunView  and 

pixrects. 

Release  4.0  Release  4.0  brings  major  enhancements  to  the  SunView  user  interface  —  ‘Search 

and  Replace’  in  text  subwindows,  shadowed  frames,  ‘Props’  frame  menu  item, 
keyboard  control  of  the  caret,  etc.  —  without  involving  major  changes  to  its  pro¬ 
grammatic  interface.  For  example,  when  programs  that  use  text  subwindows  are 
recompiled,  their  users  wiU  be  able  to  use  the  new  ‘Select  Marked  Text’  pop-up 
frame.  The  alerts  package  is  a  new  package  for  presenting  information  to  the 
user  and  allowing  him/her  to  make  choices  based  on  it. 

This  guide  was  revised  and  reprinted  again  for  4.0.  The  major  changes  are  the 
addition  of  a  new  Alerts  chapter  and  lists  of  attributes  and  functions  at  the  begin¬ 
ning  of  some  chapters  as  well  as  in  the  SunView  Interface  Summary  chapter  and 
Index. 
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On-Line  Help  For  information  on  the  programmatic  interface  to  the  on-line  help  facilities  of  the 

Sun386i  Developer' s  Guide.  The  spot  help  interface  will  be 
supported  on  all  Sun  woricstations  in  the  next  release  of  SunView. 

Code  No  Longer  Supported  Do  not  use  DEFINE_IC0N_FR0M_IMAGE  or 

DEFINE_CURSOR_FROM_lMAGE  as  these  macros  may  not  be  supported  in 
future  releases.  Instead,  use  icon_create  ( )  and  cursor_create  ( )  to 
create  the  icon  or  cursor  at  runtime.  icon_create  ( )  is  described  in  Chapter 
14,  Icons.  cursor_create  ( )  is  described  in  Chapter  13,  Cursors. 

The  old  SunWindows  stacking  menu  package  has  been  supplanted  by  the  Sun- 
View  walking  menu  package,  described  in  Chapter  12  of  this  document.  You 
should  convert  your  applications  to  use  the  menu  package,  as  the  old  package 
may  not  be  included  in  future  releases. 

The  new  a/em  package,*  described  in  Chapter  10,  replaces  use  of  the  old  (undo¬ 
cumented)  menu_pronipt  ( )  routine  in  situations  where  programs  want  to 
force  the  user  to  acknowledge  a  message  or  make  a  choice.  Alerts  are  more  flexi¬ 
ble  and  easy-to-use  than  menu_prompt  ( ) ,  and  we  strongly  encourage  you  to 
convert  to  Aem.  Again,  the  old  package  may  not  be  included  in  future  releases. 


Revision  A,  of  May  9, 1988 


The  Sun  View  Model 


The  SunView  Model . . . 

2.1.  Objects . 

Window  Objects . . 

Other  Visual  Objects . 

2.2.  Examples  of  the  use  of  Objects  by  Applications . 

2.3.  Windows . 

Frames  . 
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Subwindows . 
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Callback  Style  of  Programming . 
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Application . . . 

Calling  the  Notifier  Directly . . . 


The  Sun  View  Model 


This  chapter  introduces  the  conceptual  model  presented  by  SunView,  covering 
such  basic  concepts  as  objects,  windows  and  the  Notifier.  ^ 

It  is  important  that  you  understand  the  material  in  this  chapter  before  you  begin 
to  write  SunView  applications. 

SunView  is  an  object-oriented  system.  Think  of  SunView  objects  as  visual 
building  blocks  which  you  use  to  assemble  the  user  interface  to  your  application. 
Different  types  of  objects  are  provided,  each  with  its  particular  properties;  you 
employ  whatever  type  of  object  you  need  for  the  task  at  hand. 

The  most  important  class  of  SunView  objects  are  windows.  Not  all  objects  are 
windows,  however.  Other  visual  objects  include  cursors,  icons,  menus  and 
scroUbars. 

Technically,  an  object  is  a  software  entity  presenting  a  functional  interface.  The 
implementation  of  the  object  is  not  exposed;  you  manipulate  an  object  by  passing 
its  unique  identifier,  or  handle,  to  its  associated  functions.  The  style  of  program¬ 
matic  interface  resulting  from  this  object-oriented  approach  is  outlined  in  this 
Chapter. 

Figure  2-1  illustrates  the  different  types  and  classes  of  SunView  objects; 
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Figure  2-1  SunView  Objects 


The  different  types  of  objects  are  shown  in  normal  font;  the  classes  to  which  the 
objects  belong  are  labeled  in  italics  —  Subwindow,  Window,  and  Object. 

Each  object  type  is  described  briefly  on  the  next  page. 
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Window  Objects 


Other  Visual  Objects 


Window  objects  include /rames  and  subwindows.  Frames  contain  non¬ 
overlapping  subwindows^  within  their  borders.  Currently,  there  are  four  types  of 
subwindows  provided  by  SunView: 

□  Panel  Subwindow  —  A  subwindow  containing  pane/  items. 

□  Text  Subwindow  —  A  subwindow  containing  text. 

a  Canvas  Subwindow  —  A  subwindow  into  which  programs  can  draw. 

□  TTY  Subwindow  —  a  terminal  emulator,  in  which  commands  can  be  given 
and  programs  executed. 

The  distinctions  between  frames  and  subwindows  are  explained  in  more  detail  in 
Section  2.3,  Windows,  later  in  this  chapter.  h 

The  other  types  of  objects,  like  windows,  are  displayed  on  the  screen,  but  they 
differ  from  windows  in  that  they  are  less  general  and  more  tailored  to  their 
specific  function.  They  include: 

□  Panel  Item  —  A  component  of  a  panel  that  facilitates  a  particular  type  of 
interaction  between  the  user  and  the  application.  Panel  items  can  be  moved, 
displayed  or  undisplayed  under  program  control.  There  are  several 
predefined  types  of  items,  including  buttons,  message  items,  choice  items, 
text  items  and  sliders. 

□  Scrollbar — An  object  attached  to  and  displayed  within  a  subwindow 
through  which  a  user  can  control  which  portion  of  the  subwindow’s  contents 
are  displayed.  Both  vertical  and  horizonti  scroUbars  can  be  attached  to 
panels  and  canvases.  Text  subwindows  contain  vertical  scrollbam  by  default 
(they  cannot  contain  horizontal  scrollbars). 

□  Menu  —  An  objbct  through  which  a  user  makes  choices  and  issues  com¬ 
mands.  By  convention  in  SunView,  menus  pop  up  when  the  user  presses  the 
right  mouse  button.  Like  windows,  menus  appear  on  the  screen  when 
needed,  and  disappear  when  they  have  served  their  purpose.  Menus,  how¬ 
ever,  differ  from;  windows  in  several  ways.  First,  they  are  more  ephemeral 
— ^  a  menu  only  lemains  On  the  screen  as  long  as  the  menu  button  remains 
depress^,  ^  in  contrast  to  a  window,  which  remains  on  the  screen  until  the 
user  indicates  heifis  done  or  the  controlling  program  explicitly  undisplays  it. 
Second,  menus  are  less  flexible  than  windows;  they  are  designed  specifically 
to  allow  the  user  to  choose  from  among  a  list  of  actions. 


^  It  is  SunView’s  window  layout  policy  that  enforces  non-overlapping  subwindows,  not  some  limitation  of 
the  system.  K  you  access  the  window  system  at  a  very  low  level,  subwindows  can  overlap  successfully. 

^  The  one  exception  is  in  the  case  of  stay-up  menus,  which  will  appear  when  you  click  the  RIGHT  mouse 
button  and  disa|^>ear  when  you  click  it  again. 
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□  Alert  —  a  box  on  the  screen  which  informs  the  user  of  some  condition.  It 
has  one  or  more  buttons  which  the  user  can  push  to  dismiss  the  alert  or 
choose  a  means  of  continuing.  Like  menus,  alerts  are  ephemeral  —  they 
disappear  as  soon  as  the  user  pushes  a  button  or  otherwise  dismisses  the 
alert.  Visually,  they  resemble  simple  panels  containing  only  images,  mes¬ 
sages,  and  buttons. 

□  Pointer  —  The  object  indicating  the  mouse  location  on  the  screen. 

□  Icon  —  a  small  (usually  64  x  64  pixel)  image  representing  the  application. 

The  next  section  gives  some  examples  showing  how  typical  applications  make 

use  of  SunView  objects  in  their  user  interface. 


2.2.  Examples  of  the  use  of 
Objects  by 
Applications 

Figure  2-2 


Figure  2-2  illustrates  the  mailtool(l),  which  uses  SunView  objects  to  provide 
a  mouse-oriented  interface  to  the  SunOS  mail(l)  program: 

Mailtool 


lit!  1  root8sun.com  Mon  Dec  7  03:26 

55/1942  Tech  Mail 

2  rootesun .com 

3  spageSpolar 

4  tjacobs@snouk1ng 

5  sagssi^pages 

6  rootSsun .com 

7  rootSsun .com 

8  spagei^omega 


Sat  Dec  503:15  117/3087  Tech  Mail 

Fri  Dec  4  15:23  43/1516  what  size  to  import  scrol 

Tue  Dec  1  10:40  40/1816  Casting 

Tue  Nov  10  15:41  70/2177  Re:  new  textsu  feature 

Mon  Oct  19  22:19  55/1671  Tech  Mail 

Tue  Oct  20  22:21  141/4393  Tech  Mail 

Tue  Oct  20  13:02  36/1354  Re:  Name  completion  &  cmd 


[  Show  Next  ][  Deleti~)[  Fieply  htanpos^ 
[  Save  )[  Folder  ]Fi le:  4Tech_Mail^ 


{  Print ')[New  MaTT) 
It  Done  ] 


Misc 


From  rootSsnail  Mon  Oct  19  22:19:17  1987 
ieturn-Path;  <rootesnail> 

SlReceived:  from  snail.sun.com  by  zorba .sun .com  (3.2/341-3.2) 
id  AA19735;  Mon,  19  Oct  87  22:19:13  PDT 
Received:  by  snai 1 .sun.com  (4 ,0/SMi-3.2) 

id  AA02877;  Tue,  20  Oct  87  03:00:09  PDT 


f Inc1ude)fDe11  ver]f  Cancel 


C  Disappear 


I  To:  root8sun.com 
j Subject:  Re;  Tech  Mail 

*l  >body  of  message<  | 
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Mailtool  consists  of  a  frame  containing  three  subwindows:  a  text  subwindow  in 
which  the  message  headers  are  displayed,  a  panel  containing  various  panel  items 
(mostly  buttons)  through  which  the  user  can  give  commands  to  mail,  and  a  text 
subwindow  which  displays  the  current  message.  An  additional  text  subwindow 
and  panel  (shown  in  the  figure)  appear  when  you  press  the  reply  or  compose  but¬ 
tons. 

The  text  subwindows  contain  scroUbars,  allowing  the  user  to  bring  more  infor¬ 
mation  into  view. 

Figure  2-3  illustrates  iconedit(l),  a  simple  bitmap  editor  for  generating 
images  to  be  used  by  SunView  applications: 

Figure  2-3  iconedit 


iconedit  consists  of  a  frame  and  five  subwindows.  From  upper  left  to  lower 
right  they  are: 

□  a  panel  containing  instmctions  on  how  to  use  the  mouse; 

□  a  small  panel  for  short  messages; 

□  a  canvas  for  drawing  the  image; 

□  a  panel  containing  various  items  for  issuing  commands  and  setting  options 
such  as  the  size  of  the  image  being  drawn,  the  drawing  mode,  etc; 

□  A  small  canvas  for  viewing  the  icon  or  cursor  actual  size. 
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None  of  these  subwindows  may  be  scrolled. 


In  Figure  2-4,  the  user  has  pushed  the  New  Mail  button,  and  the  program  brings 
up  a  hour  glass  cursor  (in  the  upper  right  of  the  text  subwindow)  to  denote  that  it 
is  retrieving  mail: 


Figure  2-4  iconedit-buttons 


committing  changes  and  retrieving  new  man  > 


1 

root@sun.com 

Won 

Dec 

7 

03:28 

55/1942 

Tech  Wail 

2 

rootSsun . com 

Sat 

Dec 

5 

03:15 

117/3087 

Tech  Mail 

3 

spage@p01ar 

Fri 

Dec 

4 

15:23 

43/1518 

what  size  to  import  scrol 

4 

t jacobsSsnowk 1 ng 

Tue 

Dec 

1 

10:40 

40/1818 

Casting 

5 

sages@pages 

Tue 

Nov 

10 

15:41 

70/2177 

Re:  new  textsw  feature 

8 

rootesun.com 

Mon 

Oct 

19 

22:19 

55/1871 

Tech  Mai  1 

7 

root@sun.com 

Tue 

Oct 

20 

22:21 

141/4393 

Tech  Mai  1 

8 

spage@omega 

Tue 

Oct 

20 

13:02 

36/1354 

Re;  Name  completion  &  cmd 

(  Show  1[  next  ][  Delete  )[  Reply  jfSompose'] 
(  Save  j[  Folder  JFIIe :  +yb1nfo 


f  Mtsc  it  Done  ] 


Return-Path:  <rootesna11> 

Received:  from  snail  .sun*com  by  zorba.sun.com  (3. 2/3111-3, 2) 

Id  AA 19735;  Mon.  19  Oct  87  22:19:13  PDT 
Received:  by  sna11.sun.com  (4,0/SMI-3.2) 

Id  AA02077;  Tue,  20  Oct  87  03:00:09  PDT 
Date:  Tue,  20  Oct  87  83:00:09  PDT 
Message-Id:  <8710201000. AA02077esna11 .sun. com> 

From;  rootesun.com 
Subject;  Tech  Mall 
Apparent! y-To;  tech-list 
Status;  RO 

Sun  Tech  Mall  for  Tue  Oct  20  03:00:04  PDT  1987 

***  Requests  to  receive  tech  mall  should  be  sent  to  allasesGsun. 
****  Items  you  wish  to  post  to  tech  should  be  sent  to  techSsun. 


Today's  Topics: 


mh  wizards,  anyone? 
console  window  problem 


Date;  Mon,  19  Oct  87  14:54:11  PDT 
From;  nowIcklQspeed  (Bill  Nowicki) 

Subject;  mh  wizards,  anyone? 

I  have  heard  that  a  feature  I  added  to  sendmall  for  4.0  causes  mh 
to  break,  I  don't  use  rah,  so  could  someone  who  knows  what  It  Is 
doing  please  get  in  touch  with  me?  I  have  a  feeling  It  Is  using  the  -t 
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In  Figure  2-5,  the  user  has  pressed  the  mouse  button  over  the  Folder  panel  button 
in  the  panel: 

Figure  2-5  iconedit-menus 


rootesunTcofrt 

2  roottsun.com 

3  spagetpolar 

4  tjacobsdsnajklng 

5  sagestpagas 
5  rootQsun.com 

7  roottsun .com 

8  apagetoriaga 


Sat  Dec  583:15  117/3887  Tech  Mail 

Fri  Dec  4  15:23  43/1516  uhat  size  to  import  scrol 

Tue  Dec  1  18:48  40/1816  Casting 

Tue  Nov  18  15:41  78/2177  Re:  naiii  taxtsu  feature 

Mon  Oct  19  22:19  55/1671  Tech  Mall 

Tua  Oct  28  22:21  141/4393  Tech  Mail 

Tub  Oct  28  13:82  36/1354  Re:  Nama  completion  &  cmd 


}  Shcui  ]|  Next  ][  Delete  ]fliep1y  ][|Compose j 
Save  ]|  ho  idei  ^ecdspec 


li^rint  }f  jjeb)  MaTT] 


♦docuaant 

♦personal 

♦troff 


♦SVOOC 

♦Terml nology 
♦laff 
♦sunvIew 
♦wna^t 


♦SVMN 
♦bugs 
♦Rotlflor 
♦temi  no  logy/ 
♦ybinfo 


M1sc  ){  Done  ] 


(From  roottsnai 
Return-Path:  <l 
Received:  front 
id  AAl! 

jRecelved:  by  snail .sun. con  C4.0/SMZ-3.2J 

Id  AA92077;  Tue,  28  Oct  87  83:88:09  POT 
I  Date:  Tue,  28  Oct  87  83:88:09  POT 
|Message-Id:  <8710281090 .AA02877tsna11 .sun.con> 

I  From:  roottsun.con 
I  Subject:  Tech  Mall 
lApparently-To:  tech-list 
{status:  RO 

Sun  Tech  Mall  for  Tue  Oct  28  83:80:84  POT  1987 


***  Requests  to  receive  tech  nail  should  be  sent  to  aliases^sun. 
****  Items  you  wish  to  post  to  tech  should  be  sent  to  tech9sun.  * 


{Today's  Topics: 


mh  wizards,  anyone? 
console  window  problem 


Date:  Mon,  19  Oct  87  14:54:11  POT 
From:  nowIcklSspeed  (bill  Nowlckl) 

Subject:  mh  wizards,  anyone? 

1  have  heard  that  a  feature  I  added  to  senctnall  for  4.9  causes  mh 
to  break.  1  don’t  use  mh,  so  could  someone  who  knows  what  It  Is 
doing  please  get  in  touch  with  me?  I  have  a  feeling  It  Is  using  the  -t 


mailtool  has  displayed  a  pop-up  menu  showing  names  of  files  which  the  user 
can  insert  into  the  text  item  File:  by  selecting  a  file.  The  purpose  of  this  menu  is 
to  keep  a  current  record  of  the  mailfiles  that  the  user  has. 
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2.3.  Windows 


Frames 


There  are  two  basic  classes  of  windows  in  SunView:  overlapping/ra/wej,  which 
contain  non-overlapping  subwindows.  This  section  describes  the  distinction 
between  the  two. 


A  frame  is  not  useM  in  itself —  its  purpose  is  to  bring  subwindows  of  different 
types  together  into  a  common  frameworic  so  they  can  be  operated  on  as  a  unit.  A 
frame  is  said  to  own  the  subwindows  it  contains. 

Frames  may  also  own  other  frames.  Thus  the  basic  SunView  structure  is  a 
hierarchy  of  windows.  It  could  also  be  viewed  as  a  tree  of  windows  in  which  the 
non-leaf  nodes  are  frames  and  the  leaf  nodes  are  subwindows. 

The  frame  at  the  top  of  the  hierarchy  will  be  referred  to  in  this  document  as  the 
base  frame’,  other  frames  wiU  be  referred  to  as  subframes.^  Subframes  are  typi¬ 
cally  used  to  implement  pop-ups,  which  perform  auxiliary  functions  such  as 
allowing  the  user  to  set  options,  or  displaying  help  text.^ 

iconedit  uses  a  pop-up  for  browsing  images.  When  the  user  presses  the  but¬ 
ton  labeled  Browse,  iconedit  displays  a  pop-up  which  consists  of  a  subframe 
containing  a  single  panel  subwindow. 

Figure  2-6  illustrates  iconedit  with  its  pop-up  displayed. 


Figure  2-6  A  subframe 


Q  paint  Qj  clear  y  undo 

Points:  Pick  points  to  paint  or  clear. 

Matching  files _ 

Dir:  4  t/1cone<l1t_1nages 

F  »  ■  i  ■  g  .  i  ,  i  -  8  ■  »  ■  »  -  8  , 

File;  s.lcon 

'  8  "  1  *  1  !Ls«  1  *  I  ‘  1  "  8  *  18®*  *1  ®  i  8 

>  a  «  aamaaaaas*  saaaaan  aaaaa 

■  a  ■.  idl8a8J84*PS&!.*  a  ■  i.|«  aA  *  _  a"  _ a«’li!Ljt. 

[ loadl t store! ! brouse 1 [qutti 

I  9  I  I  «  i  ■  |  ■  |  |  ' 

sfitfiaiEisssisa 

•  «  «  «  «  9  •  «,  •  9  «  .  ■  «  *  .  «  I.  “  9  •  •  9  •  • 

aaiiiiiasiiissi 


^  Note  that  while  an  application  will  usually  be  implemented  as  a  single  base  frame  (and  its  subwindows  and 
subframes),  it  could  well  include  several  base  frames. 

^  For  details  on  pop-ups,  see  Section  4.5.1,  Pop-ups,  in  Chapter  4,  Using  Windows. 


microsystems 


Revision  A,  of  May  9,  1988 


Chapter  2  —  The  SimView  Model  1 7 


Figure  2-7 


W 

Figure  2-8 


Figure  2-7  and  Figure  2-8  illustrate  the  structures  of  iconedit  and  mail- 
tool  as  a  tree  of  windows.  Frames  are  shown  as  rectangles;  subwindows  as  cir¬ 
cles: 


Structure  of  iconedit 


Structure  of  mailtool 
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Manipulating  Frames  Via  Frames  may  be  manipulated  programmatically  by  setting  the  frame’s  attributes. 

Menus  as  described  in  Chapter  4,  Using  Windows .  Each  frame  also  has  a  menu  which 

allows  the  user  to  manipulate  the  frame  directly.  The  frame  menu  is  invoked  by 
pressing  the  RIGHT  mouse  button  on  the  exposed  parts  of  the  frame,  which 
include  the  double  lines  surrounding  the  subwindows  and  the  black/rome  header 
which  usually  appears  at  the  top  of  the  frame. 

The  menus  for  base  frames  and  subframes  differ  slightly,  as  you  can  see  from 
Figure  2-9  and  Figure  2-10.  The  first  window  shows  the  base  frame  menu;  the 
second  window  shows  the  subframe  menu: 

Figure  2-9  Base  frame  menu 
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Subwindows 


Figure  2-10  Subframe  menu 


Both  menus  contain  the  ‘Move’,  ‘Resize’,  ‘Front’,  ‘Back’,  and  ‘Redisplay’  com¬ 
mands.  ‘Move’  allows  the  user  to  change  the  frame’s  location.  ‘Resize’  allows 
him  or  her  to  change  the  window’s  width  and  height.  ‘Front’  causes  the  frame  to 
move  in  front  of  the  other  windows,  becoming  fuUy  visible  on  the  “surface”  of 
the  screen,  while  ‘Back’  does  the  opposite,  moving  the  frame  behind  any  other 
windows  occupying  the  same  portion  of  the  screen.  ‘Redisplay’  simply  causes 
the  window  to  be  displayed  again. 

When  the  user  is  finished  working  with  a  base  frame  he  may  want  to  destroy  it 
for  good,  in  which  case  he  would  choose  ‘Quit’.  Or  he  may  want  to  ‘Qose’  the 
frame,  with  the  anticipation  of  opening  it  later  and  continuing  work  where  he  left 
off.  A  base  frame  in  its  closed  state  is  represented  on  the  screen  as  a  small  (usu¬ 
ally  64  by  64  pixel)  icon.  The  icon  is  typically  a  picture  indicating  the  function 
of  the  underlying  application. 

Subframes  may  not  be  closed  into  icons;  when  the  user  finishes  with  a  subframe, 
he  simply  chooses  Done  from  the  menu.  While  not  destroying  the  subframe,  this 
causes  it  to  disappear  from  the  screen. 

Subwindows  differ  from  frames  in  several  basic  ways.  Subwindows  never  exist 
independently.  They  are  always  owned  by  a  frame,  and  may  not  themselves  own 
subwindows  or  subframes.  While  frames  can  be  moved  freely  around  the  screen, 
subwindows  are  constrained  to  fit  within  the  borders  of  the  frame  to  which  they 
belong.  Also  in  contrast  to  frames,  subwindows  are  tiled  —  they  may  not  over¬ 
lap  each  other  within  their  frame.  Within  these  constraints  (which  are  enforced 
by  a  run-time  boundary  manager)  subwindows  may  be  moved  and  resized  by 
either  a  program  or  a  user. 

So  far  this  chapter  has  discussed  the  static  aspects  of  the  SunView  model.  The 
section  below  outlines  the  system’s  model  from  a  dynamic  point  of  view. 
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2.4.  Input:  The  Notifier  SunView  is  a  notification-based  system.  The  Notifier  acts  as  the  controlling 

entity  within  a  user  process,  reading  UNIX  input  from  the  kernel,  and  formatting 
it  into  higher-level  events,  which  it  distributes  to  the  different  SunView  objects.^ 

Callback  Style  of  Programming  In  the  conventional  style  of  interactive  programming,  the  main  control  loop 

resides  in  the  application.  An  editor,  for  example,  will  read  a  character,  take 
some  action  based  on  the  character,  then  read  the  next  character,  and  so  on. 
When  a  character  is  received  that  represents  the  user’s  request  to  quit,  the  pro¬ 
gram  exits.  Figure  2-11  illustrates  this  approach: 


Figure  2-11  Flow  of  Control  in  a  Conventional  Program 
Start 


end 


Notification-based  systems  invert  this  ‘'straight  line”  control  structure.  The  main 
control  loop  resides  in  the  Notifier,  not  the  application.  The  Notifier  reads  events 
and  notifies,  or  calls  out  to,  various  procedures  which  the  application  has  previ¬ 
ously  registered  with  the  Notifier.  These  procedures  are  called  notify  procs  or 
callback  procs.  This  control  stmcture  is  shown  in  Figure  2-12. 


®  SunView  events  are  in  a  fonn  which  you  can  easily  use:  an  Asai  key  has  been  pressed,  a  mouse  buttcHi  has 
been  pressed  or  released,  the  mouse  has  moved,  the  mouse  has  entered  or  exited  a  window,  etc.  Events  are 
described  in  detail  in  in  Chapter  6,  Handling  Input. 
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Figure  2-12  Flow  of  Control  in  a  Notifier-based  Program 
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Why  a  Notification-Based 
System? 


Relationship  Between  the 
Notifier,  Objects,  and  the 
Application 


For  programmers  who  are  not  used  to  it,  this  callback  style  of  programming  takes 
some  getting  used  to.  Its  big  advantage  is  that  it  takes  over  the  burden  of  manag¬ 
ing  a  complex,  event-driven  environment  In  SunView,  an  application  typically 
has  many  objects.  In  the  absence  of  a  centralized  notifier,  each  application  must 
be  responsible  for  detecting  and  dispatching  events  to  all  the  objects  in  the  pro¬ 
cess.  With  a  centralized  Notifier,  each  component  of  an  application  receives  only 
the  events  the  user  has  directed  towards  it. 

It  is  not  necessary  for  you  to  interact  with  the  Notifier  directly  in  your  applica¬ 
tion.  SunView  has  a  two-tiered  scheme  in  which  the  packages  that  support  the 
various  objects  —  panels,  canvases,  scroUbars,  etc.  —  interact  with  the  Notifier 
directly,  registering  their  own  callback  procedures.  Ihe  application,  in  turn, 
registers  its  own  callback  procedures  with  the  object 

Typically,  when  writing  a  SunView  application  you  first  create  the  various  win¬ 
dows  and  other  objects  you  need  for  your  interface,  and  register  your  callback 
procedures  with  the  objects.  Then  you  pass  control  to  the  Notifier.  The  work  is 
done  in  the  various  callback  procedures. 

Let’s  illustrate  the  relationship  of  the  Notifier,  the  SunView  objects  and  the 
application  by  taking  iconedit  as  an  example.  Figure  2-13  illustrates  how  the 
Notifier  receives  UNIX  input  and  calls  back  to  iconedit ’s  subwindows,  which 
in  turn  call  back  to  procedures  supplied  by  iconedit. 


A 
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Figure  2-13  F/<?vw  of  Input  Events  in  iconedit ,  a  SunView  Application 


user  types,  moves  mouse,  presses  mouse  buttons... 

\  I  / 

UNIX  events:  input  on  file  descriptors 


for  panel  items 


event 

procedures 

for 

subwindows 


iconedit ’s 
event 
procedures 
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The  main  point  of  the  diagram  on  the  preceding  page  is  to  make  clear  the 
double-tiered  callback  scheme.  How  you  register  the  callback  procedures  will  be 
explained  in  the  chapters  on  panels  and  canvases. 

One  point  worth  mentioning  is  the  distinction  between  the  “event  procedures”  for 
the  canvases  and  the  “notify  procedures”  for  the  panel  items.  They  are  all  call¬ 
back  procedures,  but  they  have  different  purposes.  The  canvas’s  event  procedme 
doesn’t  do  much  work — basically  it  calls  out  to  the  application’s  event  pro¬ 
cedure  each  time  an  event  is  received.  The  application  sees  every  event  and  is 
free  to  interpret  the  events  however  it  likes. 

The  event  procedure  for  panels,  on  the  other  hand,  does  quite  a  bit  of  processing. 
It  determines  which  item  should  receive  the  event,  and  places  its  own  inteipreta- 
tion  on  events  —  the  middle  mouse  button  is  ignored,  left  mouse  button  down 
over  an  item  is  interpreted  as  a  “tentative”  activation  of  the  item,  etc.  It  does  not 
caU  back  to  the  notify  procedure  for  the  item  until  it  receives  a  left  mouse  button 
up  over  the  item.  So  panel  item  notify  procedures  are  not  so  much  concerned 
with  the  event  which  caused  them  to  be  called,  but  with  the  fact  that  the  button 
was  pushed,  or  a  new  choice  made,  etc. 

Calling  the  Notifier  Directly  As  mentioned  previously,  for  many  applications  you  will  not  need  to  call  or  be 

called  by  the  Notifier  directly  —  the  Notifier  calls  back  to  the  subwindows, 
which  in  turn  caU  back  to  your  application. 

However,  if  you  need  to  use  signals,  or  be  notified  of  the  death  of  a  child  process 
which  you  have  spawned,  you  do  need  to  call  the  Notifier  directly. 

The  Notifier  also  provides  calls  which  allow  you  to  insert  your  own  routine  in  the 
event  stream  ahead  of  a  window.  This  technique  is  known  as  interposition. 

When  and  how  to  call  the  Notifier  directly  is  covered  in  Chapter  17,  The  Notifier. 
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Interface  Outline 


This  chapter  outlines  the  SunView  interface,  the  SunView  libraries,  header  files, 
object  handles,  attributes  and  the  standard  functions  applicable  to  objects  of  each 
type. 

SunView  Libraries  The  SunView  functions  that  an  application  calls  are  mostly  in  the  library  file 

/usr/lib/libsuntool .  a  if  you  are  using  the  archive  libraries  and 
/usr/lib/libsuntool .  so  if  you  are  using  the  shared  libraries.  These 
libraries  include  the  code  to  create  and  manipulate  high-level  objects  such  as 
frames,  panels,  scrollbars  and  icons.  These  packages  in  turn  call  routines  in 
/usr/lib/libsunwindow .a  or /usr/lib/libsunwindow. so  to 
create  and  manipulate  windows  and  interact  with  the  Notifier.  These  in  turn  call 
routines  in  /usr/lib/libpixrect .  a  or  /usr/lib/libpixrect .  so 
that  do  the  drawing  on  the  screen. 

NOTE  Shared  libraries  are  introduced  in  4.0.  The  main  benefit  to  using  shared  libraries 
is  that  the  executables  are  much  smaller  (for  example,  24K  instead  of  1Mb  for 
textedit  alone)  because  the  libraries  are  loaded  dynamically  at  runtime  and  are 
subsequently  shared  by  other  executables.  Additionally,  when  the  shared 
libraries  are  recompiled,  new  functionality  is  added,  or  bug  fixes  are  made,  the 
client  applications  don’t  need  to  be  recompiled  and  linked  unless  the  .  so  or  an 
interface  changed.  For  more  information  on  shared  libraries,  see  Programming 
Utilities  and  Libraries. 

Compiling  SunView  Programs  To  compile  a  SunView  program  you  must  link  in  these  three  libraries,  and, 

because  they  are  built  one  on  top  of  another,  their  order  is  important.  For  exam¬ 
ple,  to  compile  a  typical  SunView  application  whose  source  is  rayprog .  c,  you 
would  type  in  the  command: 


Header  Files  The  basic  definitions  needed  by  a  SunView  application  —  covering  windows, 

frames,  menus,  icons  and  cursors  —  are  obtained  by  including  the  header  file 
<suntool/sunview.h>.  Definitions  for  the  other  types  of  object  are  found 
in  their  own  include  files  —  <suntool/ canvas  .h>,  <suntool/text .  h>, 
<suntool/panel .  h>,  etc. 
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Object  Handles  When  you  create  a  SunView  object,  the  creation  fimction  returns  a  handle  for  the 

object.  Later,  when  you  wish  to  manipulate  the  object  or  inquire  about  its  state, 
you  pass  its  handle  to  the  appropriate  fimction.  This  reliance  on  object  handles  is 
a  way  of  information-hiding.  The  handles  are  opaque  in  the  sense  that  you  can’t 
“see  through”  them  to  the  actual  data  structure  which  represents  the  object. 

Each  object  type  has  a  corresponding  type  of  handle.  The  window  types  of 
Frame,  Canvas,  Textsw,  Tty  and  Panel  are  grouped  under  the  type  Win¬ 
dow.  So,  for  example,  you  can  declare  a  panel  as  either  a  Panel  or  a  Window, 
whichever  is  most  appropriate.  The  other  object  types  are  Panel_item,  Menu, 
Scrollbar,  Cursor,  and  Icon. 

Since  C  doesn’t  have  an  opaque  type,  all  the  opaque  data  types  mentioned 
above  are  typedef ’d  to  the  UNIX  type  caddr_t  (for  “character  address 
type”),  which  in  turn  is  typedef’d  to  char  *. 

hi  addition  to  the  opaque  data  types,  there  are  several  t  ypedef  s  which  refer 
not  to  pointers  but  to  structs:  Event,  Pixfont,  Pixrect,  Pixwin,  Rect, 
and  Rect  list.  Generally  pointers  to  these  structs  are  passed  to  SunView  func¬ 
tions,  so  they  are  declared  as  Event  *,  Pixwin  *,  etc.  The  reason  that  the 
“*”  is  not  included  in  the  typedef  is  that  the  structs  are  publicly  available,  in 
contrast  to  the  object  handles,  which  include  the  and  which  refer  to  structs 

that  are  not  publicly  available. 

The  SunView  data  types  are  summarized  in  the  table  beginning  on  page  324  in 
Chapter  19,  SunView  Interface  Summary. 

Attribute-based  Functions  A  model  such  as  that  used  by  SunView,  which  is  based  on  complex  and  flexible 

objects,  presents  the  problem  of  how  the  client  is  to  manipulate  the  objects.  The 
basic  idea  behind  the  SunView  interface  is  to  present  a  small  number  of  fimc- 
tions,  which  take  as  arguments  a  large  set  of  attributes. 

For  a  given  call  to  create  or  modify  an  object,  only  a  subset  of  the  set  of  aU  appli¬ 
cable  attributes  will  be  of  interest.  So  that  only  the  relevant  attributes  need  be 
mentioned,  SunView  functions  make  use  of  variable-length  attribute  lists.  An 
attribute  list  consists  of  attribute/value  pairs,  separated  by  commas,  and  ending 
with  a  zero. 

Each  type  of  object  has  its  own  set  of  attributes.  The  attributes  have  prefixes 
which  indicate  the  type  of  object  they  apply  to,  i.e.  FRAME_*,  TEXTSW_*, 
CANVAS_*,  TTY_*,  PANEL_*,  MENU_*,  CURSOR_*,  ICON_*,  SCROLL_*, 
etc. 

In  addition  to  the  sets  of  attributes  applying  to  each  type  of  object,  there  is  a  set 
of  window  attributes  of  the  form  WIN_*  which  apply  to  aU  window  objects. 
These  are  attributes  such  as  WIN_height  and  win_width,  which  apply  to  all 
windows  regardless  of  whether  they  happen  to  be  panels,  canvases,  etc. 
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Standard  Functions  For  objects  of  all  t>pes  there  is  a  set  of  standard  functions  to  create  and  destroy 

the  object  and  to  get  and  set  the  object’s  attributes. 

Window  functions  are  prefixed  with  window_,  yielding 

o  window_create  () , 

□  window_get ( ) , 

n  window_set ( ) ,  and 

□  window_destroy 0  . 

Providing  common  window  functions  reduces  the  complexity  of  the  interface. 
Non- window  functions  are  prefixed  with  the  name  of  the  object.  Sb,  to  take 
menus  as  an  example,  the  standard  functions  are 

a  menu_create ( ) , 

□  menu_get ( ) , 

o  menu_set  ( ) ,  and 

□  menu_destroy ( ) . 

Example  of  SunView-Style  The  flavor  of  the  interface  is  illustrated  with  the  following  code  fragment,  which 

Programming  creates  a  scroUbar  with  a  width  of  10  pixels  and  a  black  bubble.  Later,  the 

scrollbar’s  width  is  changed  to  20  pixels.  Finally,  the  scrollbar  is  destroyed: 


Scrollbar  bar; 

\ 

bar  =  scrollbar_create (SCROLL  WIDTH, 

10, 

SCROLL  BAR  COLOR, 

SCROLL 

BLACK, 

0)  ; 

scrollbar  set (bar,  SCROLL  WIDTH, 
scrollbar  destroy (bar) ; 

20,  0); 

V _ 

j 

Note  the  zero  which  terminates  the  attribute  lists  in  the  *_create  ( )  and 
*_set  { )  calls.  The  most  common  mistake  in  using  attribute  lists  is  to  forget 
the  final  zero.  This  will  not  be  flagged  by  the  compiler  as  an  error;  however,  it 
will  cause  SunView  to  generate  a  run-time  error  message; 

Attribute  List  Size  As  you, can  see  from  the  example  above,  you  can  specify  several  attributes  in  a 

single  create  ( )  orsetO  call.  The  maximum  length  of  attribute  lists  in  Sun- 
View  is  250;  see  Maximum  Attribute  List  Sizem  Chapter  18,  Attribute  Utilities. 
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Reserved  Namespaces 


SunView  reserves  names  beginning  with  the  object  types,  as  well  as  certain  other 
prefixes,  for  its  own  use. 


The  prefixes  listed  below  should  not  be  used  by  applications  in  lower,  upper,  or 
mixed  case. 


Table  3-1  Reserved  Prefixes 


ACTION 

icon_ 

scroll 

alert 

menu_ 

seln_ 

attr_ 

notify_ 

textsw_ 

canvas_ 

panel_ 

text_ 

cursor_ 

pixrect_ 

toolsw_ 

default s_ 

pixwin 

tool_ 

ei _ 

pr_ 

ttysw__ 

es__ 

pw 

tty_ 

event_ 

rect_ 

window_ 

ev 

rl_ 

win 

frame 

help_ 

scrollbar_ 

wmgr_ 

o 
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Table  4-1 


Summary  Listing  and  Tables 


This  chapter  describes  how  to  build  SunView  applications  out  of  frames  and 
subwindows. 

The  first  section  presents  the  basic  window  routines.  Succeeding  sections  give 
examples,  ranging  from  the  simplest  possible  application  to  a  moderately  useful 
file  manager.  For  quick  reference,  the  examples  are  given  in  the  table  below: 


Window  Usage  Examples 


Example 

Description 

Illustrates 

Page 

hellojvorld 

Minimal  SimView  program. 

Compilation,  frames. 

37 

simple  jranel 

Panel  w/message  and  button. 

Basic  attributes,  panels. 

39 

lister 

Front  end  to  Is 

Panels,  tty  subwindows. 

42 

filer 

File  manager 

Pop-ups,  Selection  Service. 

44 

image  brcfwser  l 

Displays  images 

Subwindow  layout. 

50 

image  browser _2 

Displays  images 

Row/column  space. 

53 

To  give  you  a  feeling  of  what  you  can  do  with  frames  and  subwindows,  the  fol¬ 
lowing  page  lists  the  available  window  and  frame  attributes,  functions  and  mac¬ 
ros.  Many  attributes  are  discussed  as  they  occur  in  the  examples,  and  in  other 
chapters  (use  the  Index  to  check).  However,  this  chapter  does  not  attempt  com¬ 
plete  coverage  of  all  the  attributes.  All  are  briefly  described  with  their  arguments 
in  the  window  and  frame  summary  tables  in  Chapter  19,  SunView  Interface  Sum¬ 
mary: 

□  the  Window  Attributes  table  begins  on  page  379; 

□  the  Frame  Attributes  table  begins  on  page  382; 

□  the  Window  Functions  and  Macros  table  begins  on  page  384; 

□  the  Command  Line  Frame  Arguments  table  begins  on  page  386. 
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Window  Attributes 

WIN_BELOW 

WIN_FIT_WIDTH 

WIN_PERCENT_WI DTK 

WIN_BOTTOM_MARGIN 

WIN_FONT 

WIN  PICK  INPUT  MASK 

WIN_CLIENT_DATA 

WIN  GRAB  ALL  INPUT 

WIN_PIXWIN 

WIN_COLUMNS 

WIN_HEIGHT 

WIN_RECT 

WIN_COLUMN_GAP 

WIN_HORIZONTAL_SCROLLBAR 

WIN_RIGHT_MARGIN 

WIN_COLaMN_WI DTK 

WIN  IGNORE  KBD  EVENT 

WIN_RIGHT_OF 

WIN_CONSUME_KBD_EVENT 

WIN  IGNORE  KBD  EVENTS 

WIN_ROW_GAP 

WIN_C0NSUME_KBD_EVE1SITS 

WIN  IGNORE  PICK  EVENT 

WIN_ROW_HEIGHT 

WIN_CONSUME_P I CK_EVENT 

WIN  IGNORE  PICK  EVENTS 

WIN_ROWS 

WIN_CONSUME_P I CK_EVENTS 

WIN_INPUT_DESIGNEE 

WIN_SCREEN_RECT 

WIN_CURSOR 

WIN_KBD_FOCUS 

WIN_SHOW 

WIN_DEVICE_NAME 

WI N  KBD  INPUT  MASK 

WIN_TOP_MARGIN 

WIN_DEVICE_NUMBER 

WIN_LEFT_MARGI N 

WIN_TYPE 

WIN_ERROR_MSG 

WIN_MENU 

WIN_VERT I CAL_SCROLLBAR 

WIN_EVENT_PROC 

WIN_MOUSE_XY 

WIN_WIDTH 

WIN_EVENT_STATE 

WIN_NAME 

WIN_X 

WIN_FD 

WIN_OWNER 

WIN_Y 

WIN_FIT_HEIGHT 

WI N_PERCENT_HEI GHT 

Frame  Attributes 

FRAME_ARGS 

FRAME_DEFAULT_DONE__PROC 

FRAME_NO_CONFIRM 

FRAME_ARGC_PTR_ARGV 

FRAME_DONE_PROC 

FRAME_NTH_SUBFRAME 

FRAME_BACKGROUND_COLOR 

FRAME_EMBOLDEN_LABEL 

FRAME_NTH_SUBWINDOW 

FRAME_CLOSED 

FRAME_FOREGROUND_COLOR 

FRAME_NTH_WINDOW 

FRAME_CLOSED_RECT 

FRAME_ICON 

FRAME_OPEN_RECT 

FRAME_CMDLINE_HELP_PROC 

FRAME_INHERI T_COLORS 

FRAME_SHOW_LABEL 

FRAME_CURRENT_RECT 

FRAME_LABEL 

FRAME_SUBWINDOWS_ADJUSTABLE 

Window  Functions  and  Macros 


window_bell (win) 

window_create (owner,  type,  attributes) 

window  default  eventproc (window,  event,  arg) 

window_destroy (win) 

window_done (win) 

window_f it (win) 

window_f it_height (win) 

window  fit  width (win) 


window_get (win,  attribute) 
window_loop ( subframe) 
window_ma  in_l  o  op  ( ba  s  e_f  r ame ) 
window_read_e vent (window,  event) 
window_refuse_kbd_focus (window) 
window_release_event_lock (window) 
window_return (value) 
window  set (win,  attributes) 
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4.1.  Basic  Routines 


Creating  a  Window 


Initiating  Event  Processing 


Modifying  and  Retrieving 
Window  Attributes 


This  section  introduces  the  basic  routines  for  using  windows.  It  explains  how  to 
create,  modify,  and  destroy  windows. 

You  create  all  windows  with  the  function: 

Window 

window_c reate (owner,  type,  attributes) 

Window  owner; 

<windowtype>  type; 

<attribute-list>  attributes; 

If  you  recall  from  Chapter  2,  The  SunView  Model,  a  SunView  application  is 
implemented  as  a  hierarchy  of  frames.  Each  frame  owns  one  or  more  subwin¬ 
dows.  The  frame  at  the  top  of  the  hierarchy  (the  base  frame)  will  have  a  null 
owner.  In  the  above  function,  the  owner  parameter  is  the  handle  of  the  window 
to  which  the  window  returned  by  window_create  ( )  will  belong.  The  type 
parameter  is  the  type  of  the  new  window;  for  example,  FRAME,  PANEL, 
TEXTSW,  CANVAS,  or  TTY. 

A  very  simple  example  of  this  function  would  be  to  create  a  panel  belonging  to  a 
frame  called  base_f  rame,  you  would  use; 

Panel  panel; 

window_create (base_f rame.  Panel,  0); 

The  window_create  0  call  does  not  display  the  frame  on  the  screen.  You 
bring  it  to  life  after  creating  a  base  frame  and  its  subwindows  and  subframes,  by 
calling  window_main_loop  (base_f  rame) .  This  call  displays  the  frame 
on  the  screen  and  begins  processing  the  events  by  passing  control  to  the  Notifier. 
Chapter  2,  The  SunView  Model,  gave  a  brief  explanation  of  the  Notifier. 

Keep  in  mind  that  subframes  are  treated  different  from  base  frames  because  they 
are  not  tied  to  the  base  frame  that  is  activated  in  the  window_main_loop  ( ) 
call,  hi  addition,  if  you  create  a  subframe  with  WIN_SH0W  set  to  TRUE,  when 
the  user  tries  to  manipulate  the  subframe  ‘garbage’  data  will  appear  on  the 
screen. 

You  modify  and  retrieve  the  value  of  window  attributes  with  the  following  two 
functions: 

int 

window__set  (window,  attributes) 

Window  window; 

<attribute-list>  attributes; 

caddr_t 

window_get (window,  attribute) 

Window  window; 

Window  attribute  attribute; 
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Destroying  Windows 


NOTE  If  you  call  window_get  ( )  and  specify  an  inappropriate  attribute,  a  zero  will 

be  returned.  For  example,  a  sub  frame  cannot  be  closed.  Therefore,  the  call 
window_get  ( sub_f  rame ,  FRAME_CLOSED_RECT )  will  not  work,  so  the 
value  returned  will  be  zero.  A  segmentation  violation  will  occur  if  an  attempt  is 
made  to  dereference  the  return  value. 

When  you  get  a  pointer  back  from  window_get  ( ) ,  the  pointer  points  into  a 
private  data  structure,  whose  contents  may^change.^ 

You  destroy  windows  with  the  following  two  functions: 
int 

window_destroy (window) 

Window  window; 


int 

window_done (window) 

Window  window; 

The  difference  between  these  two  is  that  window_destroy  ( )  destroys  only 
window  and  its  subwindows  and  subframes.  window_done  ( ) ,  on  the  other 
hand,  destroys  the  entire  hierarchy  to  which  the  subwindow  or  subframe  belongs. 

When  window_destroy  ( )  is  called  on  a  window,  the  corresponding  file 
descriptors  cannot  be  used  again  until  the  Notifier  is  called.  The  file  descriptor 
associated  with  the  window  is  not  reclaimed  until  the  notifier  has  a  chance  to  dis¬ 
tribute  notifications  again. 

The  way  window_de  st  roy  ( )  works  is  that  it  asks  the  window  owner  if  it  is 
willing  to  be  destroyed.  If  so,  it  queues  up  a  notification  procedure  to  destroy  the 
window.  This  delay  protects  the  program  from  destroying  a  window  that  is  being 
accessed  in  the  current  call  stack.  You  can  work  around  this  restriction,  assum¬ 
ing  you  never  reference  this  window  again,  by  calling 
notify_f  lush_pending  ( )  after  calling  window_destroy  ( ) . 


^  For  most  attributes  the  pointer  returned  vv’indow_get  ( )  points  into  per-window  storage,  but  for  some 
the  storage  is  static,  per-process  data.  These  attributes  are  flagged  in  the  tables  Chapter  19,  SunView  Interface 
Summary. 
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4,2.  Example  1 — 

hello  world 


In  learning  a  new  programming  language  or  environment,  it  usually  helps  to 
begin  with  a  small  program  that  simply  prints  some  output.  By  creating,  compil¬ 
ing,  loading,  and  running  the  program,  you  will  master  the  mechanical  details. 
Here  is  a  small  SunView  program: 

- - - —  > 

#include  <suntool/sunview .h> 

main  () 

{ 

Frame  frame; 

frame  =  window_create (NULL,  FRAME, 

FRAME_LABEL,  "hello  world", 

0); 

window_main_loop (frame) ; 

} 


After  you  create  the  above  program  in  a  file  called  hello_world .  c,  you  com¬ 
pile  it  with  the  command: 

%  cc  -o  hello_world  hello^world.  c  -Isvmfcool  -Isunwindow  -Ipixrect 

Where, 

□  hello_wor  Id  is  the  executable  output  file  that  will  be  created 

□  -Isuntool  specifies  to  link  with  the  suntool  object  library 

□  -Isunwi ndo w  specifies  to  link  with  the  sunwindow  object  library 

□  -Ipixrect  specifies  to  link  with  pixrect  object  library 

After  you  compile  the  program,  type  “heUo_world”,  and  the  window  will  come 
up  as  shown  in  Figure  4-1  a  single  frame  with  the  words  “hello  world”  in  the 
frame  header: 
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Figure  4-1  Hello  World  Window 


ilLJII.MIMjHII 


hello 

uorld 


This  window  is  “alive”  within  the  SunView  user  interface;  it  can  be  closed, 
moved,  resized,  hidden,  etc.  When  closed,  a  default  icon  is  displayed,  which 
contains  the  text  from  the  frame  header. 
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4,3.  Example  2 The  next  program  is  more  complex  than  the  first  program.  It  creates  a  frame  that 

simple  j)anel  contains  a  frame  label  and  a  panel  that  contains  a  panel  button  and  a  message. 

This  program  also  includes  an  image  that  appears  when  the  window  closes  down 
tchan  icon.  Some  basic  attributes  dealing  with  fonts,  icons,  help,  error  messages 
and  parsing  command-line  flags  are  introduced. 


#±nclude  <stdio.h> 

#include  <suntool/sunview.h> 
tinclude  < suntool /panel .h> 
#include  <suntool/icon .h> 


static  void  quit_proc(); 

Frame  frame; 

Panel  panel; 

Pixfont  *bold; 

Icon  icon; 

static  short  icon_image[]  =  { 
tinclude  <images/hello_world. icon> 

}; 

mpr_static {hello_world,  64,  64,  1,  icon_image) ; 


main(argc,  argv) 

int  argc;  char  **argv; 

{ 

bold  =  pf_open{"/usr/lib/fonts/fixedwidthfonts/screen.b.l2”) ; 

if  (bold  ==  NULL)  exit{l); 


icon  =  icon  create (ICON_IMAGE,  &hello_world,  0) ; 


frame  =  window_create (NULL,  FRAME, 
FRAME_LABEL, 
FRAME_ICON, 
FRAME_ARGS, 

WI N_ERROR_MSG , 

0)  ; 


"hello_world_panel" , 
icon, 

argc,  argv, 

"Can't  create  window.". 


panel  =  window__create  (frame,  PANEL,  WIN_FONT,  bold,  0); 


panel  create_item (panel,  PANEL_MESSAGE, 

PANEL_LABEL_STRING,  "Push  button  to  quit.",  0); 
panel_create_item (panel ,  PANEL_BUTTON , 

PANEL_LABEL_IMAGE ,  panel_button_image (panel,  "Good-bye",  0,  0) , 
PANEL_NOTIFY_PROC,  quit_j>roc, 

0)  ; 


window_f it (panel) ; 
window_f it (frame) ; 
window_main_loop (frame) ; 

} 

static  void 
quit__proc  () 

{ 

window  set (frame,  FRAME _ NO _ CONFIRM,  TRUE,  0) ; 

window_destroy (frame) ; 

} 
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This  program  creates  a  frame  containing  a  single  panel  with  a  message  and  a  but- 
ton: 

Figure  4-2  Hello  World  Panel 


Some  Frame  Attributes 


FRAME  LABEL 


FRAME  ICON 


WIN  ERROR  MSG 


hel  lo_iJorld_panel 


Push  button  to  quit.  [Goodbye] 


The  features  and  attributes  used  in  the  above  program  are  discussed  below. 


The  attributes  are  discussed  below  in  the  order  that  they  appear  in  the  above 
panel. 

The  string  given  as  the  value  for  FRAME_LABEL  wiU  appear  in  a  black  frame 
header  strip  at  the  top  of  the  frame.  If  you  do  not  want  the  label  and  the  frame 
header  to  appear,  then  set  the  attribute  frame  show  label  to  FALSE. 


The  program  used  FRAME_lCON  to  specify  the  icon  to  be  shown  when  the  frame 
is  closed.  This  is  done  by  first  using  the  macro  mprstatic  ( )  to  define  a 
static  memory  pixrect  that  contains  this  data.  Where  hello_world  is  the 
name  of  the  pixrect  to  be  defined.  The  next  three  arguments  specify  the  width, 
height,  and  depth  of  the  image.  Typically,  for  an  icon,  this  is  64,  64,  and  1.  The 
final  argument  is  an  array  of  shorts  that  contains  the  bit  pattern  of  the  icon  image. 
It  takes  its  image  from  the  file 

/usr/ include/ images/hello_world .  icon.  This  statically  defined 
image  is  passed  to  icon_create  { )  at  runtime. 


The  application  uses  frame_ARGS^  to  pass  command-line  arguments  given  by 
the  user  to  the  frame.  A  set  of  command  line  arguments  are  recognized  by  aU 
frames.  These  arguments  allow  the  user  to  control  such  basic  attributes  as  the 
frame’s  dimensions  and  label  and  whether  the  frame’s  initial  state  is  open  or 
closed,  etc.  These  arguments  begin  with  -W\  for  a  complete  list  of  them  see  the 
Command  Line  Frame  Arguments  table  in  Chapter  19,  SunView  Interface  Sum¬ 
mary. 


WlN_ERROR_MSG  provides  a  simple  form  of  error  checking.  If  this  attribute  is 
not  specified,  then  window_create  {)  will  return  0  on  failure.  If  a  value  for 
WlN_ERROR_MSG  is  Specified  and  window_create  ( )  fails,  then  it  will  print 
the  error  message  on  stderr  and  exit  with  a  status  of  1. 


®  As  an  alternative  to  PRAME_ARGS,  you  can  use  FRAME_ARGC_P  TR_ARGV,  which  takes  a  pointer  to 
argc,  rather  than  argc  itself.  This  attribute  causes  window_create  ()  to  strip  all  argumoits  beginning  with 
-W  out  of  argv,  and  decrement  argc  accordingly. 
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Panels  The  panel  is  created  by  calling  window_create  ( )  with  the  previously  created 

frame  as  the  owner  and  PANEL  as  the  window  type. 

By  default,  text  in  the  panel  is  rendered  in  the  default  system  font,  which 
window_create  ( )  obtains  by  calling  pf_def  ault  ( )  The  program 
specified  a  font  by  first  opening  the  font  with  pf_open  ( ) ,  and  then  passing  it 
into  the  panel  as  WIN_F0NT. 

In  the  SunView  context,  note  that  setting  WIN_FONT  is  not  equivalent  to  specify¬ 
ing  a  font  at  run  time  with  the  -Wt  command-line  argument:  -Wt  opens  the 
default  system  font,  WIN_FONT  doesn’t.  The  only  window  types  that  currently 
make  use  of  win_FONT  to  render  characters  are  panels  and  text  subwindpws. 

Panel  Items  The  panel  contains  two  panel  items:  the  message  saying  “Push  button  to  quit.” 

and  the  Good-bye  button.  They  are  created  with  panel_cr  eate_item  ( ) . 

Notify  Procedure  The  concept  of  callback  procedures  was  introduced  in  Chapter  2,  The  SunView 

Model.  Callback  procedures  for  panel  items  are  known  as  notify  procedures. 

The  program  registered  its  notify  procedure  quit_proc  ( )  with  the  Quit  but¬ 
ton  using  the  attribute  PANEL_NOTIFY_PROC.  quit_jproc  ( )  is  called  when 
the  user  selects  the  button.  It  in  turn  calls  window_de  st  r  oy  () ,  which,  as 
explained  in  the  eailier  subsection  on  Destroying  Windows,  causes 
window_main_loop  ( )  to  return.  Before  calling  window_destroy  { ) ,  it 
disables  the  standard  SunView  confirmation  by  setting  the  attribute 
FRAME_NO_CONF  IRM  for  the  frame. 

The  final  feature  illustrated  by  the  example  is  the  use  of  the  window_f  it  { ) 
macro.  This  macrd  causes  a  window  to  exactly  fit  its  contents. 

The  contents  of  a  Janel  are  its  panel  items;  the  contents  of  a  frame  are  its  subwin¬ 
dows.  Therfore,  the  example  program  calls  window_f  it  0  twice,  first  fitting 
the  panel  around  its  two  items,  then  fitting  the  frame  around  its  panel. 

A  window_fit_width  0  macro  and  a  window_f it_height  ()  macro 
are  used  to  permit  adjusting  in  only  one  dimension.  These  correspond  to  the 
window  attributes  WIN_FIT_WIDTH  and  WIN_FIT_HEIGHT. 

Since  Release  3.2,  if  you  use  window_f  it  ( )  or  its  variants  for  sizing  the 
width  and  height  of  a  frame,  you  need  to  be  careful  that  the  subwindows  have 
some  specified  size,  or  they  wiU  be  shrunk  very  small  by  the  window_f  it  ( ) 
call.  Usually  you  give  a  subwindow  a  fixed  size  in  one  or  both  dimensions,  or 
size  it  to  be  a  percentage  of  the  frame’s  size.  The  default  size  of  a  frame  is  that  it 
encloses  an  area  34  rows  by  80  columns  in  its  default  font. 


^  For  details  on  fraits  the  Pixrect  R^erence  Manual. 
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4.4.  Examples — lister  Figure  4-3  illustrates  a  program  to  help  manage  files.  The  fimt  version  simply 

lets  the  user  list  files  in  the  current  directory,  forming  a  ftont-end  to  the  ls(l) 
command: 


Figure  4-3  lister 


File:  *.0 


[  ]  [  Quit  ] 


cora1%  Is  *.0 
995-^00  Is.c 
canvas_demo.c 
confirm. c 
dg_cyc1e.c 
dirtool.c 
f1 ler .c 
f1 ler3_save.c 
|cora1%  [] 


filer_save.c 

gsh.panel.c 

hello.uorld.c 

he11o_uor1d2.c 

he1per_save.c 

helper.versi onl . c 

1con_te8t.c 


I  leaf .c 
1teffls_deno.c 

II  star. c 
locKscreen.c 
narg1n_test.c 
Misc_merge.c 
order.testl.c 


order_test2.c 
ordBr_test3.c 
order_test4.c 
panel .c 
panel_text.c 
sunvi eu_nanual . c 


The  tool  presents  two  subwindows.  The  top  subwindow  is  a  control  panel  with  a 
text  item.  It  contains  a  place  to  specify  the  files  to  be  listed,  a  List  button,  and  a 
Quit  button. 

Below  the  control  panel  is  a  tty  subwindow.  When  the  user  pushes  the  List  but¬ 
ton,  the  program  constructs  a  command  string  consisting  of  the  string  “Is  ”,  fol¬ 
lowed  by  the  value  of  the  File:  item,  followed  by  a  newline,  and  inputs  the  com¬ 
mand  string  to  the  tty  subwindow  by  calling  ttysw_input  ( ) . 

The  program  is  listed  in  its  entirety  below. 

Notice  that  the  frame,  the  panel  and  the  tty  subwindow  are  aU  declared  as  type 
Window.  They  could  just  as  well  have  been  declared  as  type  Frame,  Panel 
and  Tty. 


Revision  A,  of  May  9, 1988 


Chapter  4  —  Using  Windows  43 


#include  <suntool/sunview.h> 
tinclude  < sunt ool /panel .h> 

#include  <suntool/tty.h> 

Window  frame,  panel,  tty; 

Panel_item  fname_item; 

static  void  ls_proc(),  quit_proc  ()  ; 

main (argc,  argv) 

int  argc;  char  **argv; 

{ 

frame  =  window_create (NULL,  FRAME, 

FRAME_ARGS,  argc,  argv, 

FRAME_LABEL,  "lister", 

0); 

panel  —  window_create (frame,  PANEL,  0); 

create_panel_items () ; 

tty  =  window_create (frame,  TTY,  0); 

window_main_loop (frame) ; 

exit (0) ; 

} 

createj>anel_items  () 

{ 

fname_item  =  panel_create_item (panel,  PANEL_TEXT, 
PANEL_LABEL_STRING,  "File:  ", 

PANEL_VALUE_DISPLAY_LENGTH,  55, 

0)  ; 

panel__create_item  (panel ,  PANEL_BDTTON , 

PANEL_LABEL_IMAGE ,  panel_button_image (panel,  "List",  5,  0) , 
PANEL_NOTIFY_PROC,  ls_proc, 

0); 

panel_creat e_i tem  (panel ,  PANEL_BUTTON , 

PANEL_LABEL_IMAGE,  panel_button_image (panel,  "Quit",  5,  0) , 
PANEL_NOTI FY_PROC ,  quit_proc , 

0)  ; 

window_fit_height (panel) ; 

} 

static  void 

ls_proc(/*  ARGS  UNUSED  */) 

{ 

char  cmdst ring [256]  ; 

sprintf (cmdstring,  "Is  %s\n",  panel_get_value (fname_item)  )  ; 
ttysw  input (tty,  cmdstring,  strlen (cmdstring) ) ; 

static  void 

quit_proc (/*  ARGS  UNUSED  */) 

{ 

window_de St roy (frame) ; 

} 
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4.5.  Example  4 — filer 


Our  next  example  builds  on  the  simple  front  end  to  Is  given  in  the  previous 
example  to  create  a  more  interesting  file  manipulation  tool.  This  application 
illustrates  the  use  of  the  text  subwindow,  the  Selection  Service,  and  pop-ups  — 
windows  that  appear  on  the  screen  and  disappear  dynamically  during  execution 
of  a  program. 


In  appearance, is  similar  to  lister,  in  that  it  contains  a  control  panel  and  tty 
subwindow.  The  user  specifies  the  directory  and  file,  and  pushes  ie  List  button, 
causing  the  Is  command  to  be  sent  to  the  tty  subwindow: 


Figure  4-4  filer 


f  1  ler 


(List  Directory]  [Set  Is  flags]  [Edit]  (Delete]  (Quit] 
Filing  Mode:  C  Use  "File;"  item 


Di  rectory :  /usr/vi  euj/doc/app/code 
File: 


.c 
_ ♦ 


/usr/view/doc/app/code/conf i rm .c 
/usr/vi euj/doc/app/code/dctool  .c 
/usr/view/doc/app/code/f i ler .c 
/usr/vi  eLj/doc/app/code/font_menu .  c 
/usr/view/doc/app/code/hel  lo_ujorld  .c 
/usr/vi ew/doc/app/code/image_browser_l , c 
/usr/vieuj/doc/app/code/image_brouiser_2  .c 
/usr/vi ew/doc/app/code/l ister .c 
/usr/view/doc/app/code/menugenproc  .c 
/usr/vi  eui/doc/app/code/resizB_denio  .c 
/usr/vieuj/doc/app/code/seln_denio  ,c 
/usr/view/doc/app/code/showcolor .c 
/usr/vi  euj/doc/app/code/simpl  e_canvas .  c 
/usr/vi ew/doc/app/code/simp1e_panel ,c 
/usr/view/doc/app/code/spheres.c 
/usr/vi  GLj/doc/app/code/tty_i o  ,  c 
/usr/vi Bw/doc/app/code/typein .c 
polar'A  [] 


There  are  three  new  buttons,  each  of  which  illustrates  a  typical  use  of  pop-ups: 

Set  Is  flags  a  pop-up  property  sheet  for  setting  options  to  Is; 

Edit  a  pop-up  text  subwindow  for  browsing  and  editing  files; 

Delete  a  pop-up  confirmer  which  forces  the  user  to  confirm  or  cancel. 

The  three  buttons  are  discussed  in  the  pages  that  follow.  The  discussion  makes 
reference  to  specific  routines  in  the  filer  program,  which  is  listed  in  its  entirety  as 
filer  m  Appendix  A,  Example  Programs. 
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Pop-ups  In  SunView,  pop-ups  are  implemented  as  subframes  containing  subwindows. 

The  subframe,  along  with  its  subwindows,  is  displayed  and  undisplayed  as 
needed.  Pop-ups  may  be  displayed  in  either  a  blocking  or  a  non-blocking  mode. 
Examples  of  SunView  pop-ups  include  the  mailtool’s  composition  window  and 
textedit’s  search  and  replace. 


Pop-up  Text  Subwindow  The  Edit  button  illustrates  a  non-blocking  pop-up.  When  the  user  selects  a 

filename  and  presses  the  button,  a  pop-up  text  subwindow  containing  the  file 
appears: 

Figure  4-5  A  Pop-up  Text  Subwindow 


I 


[List  Pi  rectory^  [Set  Is  flags]  [Edit]  [Delete]  [Quit] 


Filing  Mode:  O  Use  "File:"  item 

Di  rectory :  /usr/vi  eui/doc/app/code 
File:  confirm.c 


/usr/vieuj/doc/app/code/conf  i  rm  .c 
/usr/vleui/doc/app/code/dctool  .c 
/usi 


conf 1 rm . c 


/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

/usr 

|po1a 


^  3|!  3|e  4: 9|C  4:  4c  4s  V  V  V  :) 


Ic4c4c4e4c4e4c4<4s4s4e4s4cs|s4t4 


#ifndef  lint 

static  char  sccsid[]  ■  "@(#JcQnf i rm .c  1.4  87/01/07  Copyr  1| 
986  Sun  Micro"j 
#endif 

^4c4:9|c4:4c4i;4(4:4c4c4c4e#4c3^4c4c4c4c%4e3^4e4c4c4c4c4c4c4c4c9|e4E4;4c4c4;4c4c9|c4E4c4c4e4cs|c4E4‘3^4E4E4<3^4::^4s^ 
/ 

iPinclude  <suntool/sunvieu.h> 

#includB  <suntool /panel .h> 

static  Frame  init_confirmerCJ ; 

static  int  confirmO; 

static  void  yes_no_ok(); 


int 

conf i rm_yes(message) 


Both  the  subframe  and  text  subwindow  for  the  pop-up  are  created  at  initialization 
time  with  the  calls: 


edit_frame  =  window_create {base_f rame,  FRAME, 

frame_show_lAbel,  true, 

0); 

editsw  =  window_create (edit_f rame,  TEXTSW,  0); 

V _ ^ _ _ _ 


When  the  user  selects  the  Edit  button,  the  notify  procedure  edit_pr  oc  ( )  is 
invoked.  This  function  first  calls  the  Selection  Service  to  get  the  name  of  the  file 
the  user  has  selected. 
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It  then  loads  the  file  into  the  text  subwindow,  sets  the  frame  header  to  the 
filename,  and  displays  the  frame  with  these  two  calls: 

f - - - s 

window_set (editsw,  TEXTSW_FILE,  filename,  0) ; 

window_set (edit_frame,  FRAME_LABEL,  filename,  WIN_SHOW,  TRUE,  0) ; 
V _  > 


Pop-up  Property  Sheet  The  property  sheet  shown  in  Figure  4-6  is  a  typical  example  of  a  non-blocking 

pop-up.  By  pushing  the  Set  Is  flags  button,  the  user  can  get  a  property  sheet 
which  allows  him  to  set  some  of  the  options  to  the  Is  command.  While  the  pro¬ 
perty  sheet  is  displayed,  the  user  can  continue  to  interact  with  the  application, 
setting  options  now  and  then.  The  user  can  cause  the  pop-up  to  disappear  at  any 
time  by  pushing  the  Done  button,  selecting  Done  from  the  subframe’s  menu,  or 
by  pressing  the  SunView  function  key  labelled  I  Open  I. 

Figure  4-6  A  Non-blocking  Pop-up 


filer 


[List  Directory]  [Set  Is  flags]  [Edit]  [Deletel  [Quit] 
Filing  Mode;  O  Use  "File:"  item 


Di  rectory :  /usr /vieuj /doc /app /code 

File:  confirm. c 

♦ 

/usr/vieu)/doc/app/code/conf  i  rm  .c 
/usr/vieu) 

/usr/vieuj 
/usr/vieui 
/usr/vieuj 
/usr/view 
/usr/vieu 
/usr/vieu 
/usr/vieu 
/usr/vieu 
/usr/vieu 
/usr/vieu 
/usr/vieu 
/usr/vieu 
/usr/vieu 
/usr/vieu 

/usr /vi eu/doc/app/code/typei  n . c 
polar'A  [] 


/doc/app/code/dctool .c 
/doc/app/code/f i ler ,c 
/<i 
/. 

/. 

/< 

/( 

/( 

/( 
h 
/. 


Options  for  Is  command 


^ormat : 

Sort  Order: 

Sort  criterion: 

-or  directories,  list: 

Recursively  list  subdirectories?  O  No 
Indicate  type  of  file?  O  No 


[Done] 


C  Short 
G  Descending 
G  Name 
G  Contents 


Invoking  the  ‘Props’  Menu  Item  Two  attributes  are  used  to  control  whether  the  ‘Props’  menu  item  is  active  or  able 

to  be  invoked  in  the  frame’s  menu.  The  code  fragment  given  below  is  taken 
from  the  filer  program. 

The  FRAME_PROPS_ACTlON_PROC  attribute  specifies  which  procedure  will 
be  called  when  the  ‘Props’  menu  item  is  chosen  or  the  [  Props  I  key  is  pressed.  In 
the  code  below,  FRAME__PROP  S_PROC  specifies  that  the  procedure 
ls_f  lags_proc  ( )  is  called  when  the  t  Props  1  key  is  pressed. 


Asun 
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WIN  SHOW 


Pop-Up  Confirmer 


The  FRAME__PROP  S_ACT  IVE  attribute  specifies  whether  the  procedure  that  is 
specified  by  the  frame_props_action_PROC  will  be  called  or  not.  If  the 
attribute  frame_PROPS_ACTIVE  is  TRUE,  then  the  frame  menu  will  contain 
an  un-greyed  ‘Props’  menu  item.  If  the  attribute  frame_props_active  is 
FALSE,  then  the  frame  menu  will  contain  a  greyed  out  ‘P*rops’  menu  item. 


base  frame  =  window_c reate (NULL,  FRAME, 

- - 

FRAME_ARGS, 

argc,  argv. 

FRAME_LABEL, 

"filer". 

FRAME^PROP S_ACT ION_PROC , 

ls_f lags_proc. 

FRAME  PROPS  ACTIVE, 

TRUE, 

0)  ; 

1, 

y 

The  display  of  a  non-blocking  pop-up  is  controlled  using  the  WIN_SH0W  attri¬ 
bute.  The  initialization  routine  Great e_ls_f  lags_j)opup  { )  creates  the 
subframe,  panel,  and  panel  items  for  the  property  sheet.  When  the  subframe  is 
created,  WIN_SHOW  is  FALSE.^^  The  notify  procedure  for  the  Set  Is  flags  but¬ 
ton,  ls_f  lags_proc  ( ) ,  simply  sets  WIN_SH0W  to  TRUE  for  the  subframe. 

When  the  notify  procedure  for  the  List  button,  ls_proc  { ) ,  is  called,  it  calls 
compose_ls_options  ( )  to  construct  the  appropriate  string  of  flags  based 
on  the  settings  of  the  items  in  the  property  sheet. 

Both  the  property  sheet  and  the  editing  subwindow  described  in  the  preceding 
section  are  examples  of  non-blocking  pop-ups,  in  which  the  application  contin¬ 
ues  to  receive  input  while  the  pop-up  is  displayed. 

Blocking  pop-ups  differ  in  that,  when  displayed,  they  receive  aU  input  directed  to 
the  screen.  Blocking  pop-ups  are  appropriate  when  you  want  to  force  the  user  to 
confirm  or  cancel  an  irreversible  operation  before  changing  the  application’s 
state  in  any  way. 

Most  uses  of  blocking  pop-ups  should  use  the  alert  package  described  in  Chapter 
10,  Alerts.  In  the  example  given  below,  filer  uses  an  alert  for  the  Delete  button 
confirmation.  However,  if  you  want  to  use  other  panel  features,  or  other  kinds  of 
windows,  then  you  can  use  window_loop  ( )  for  the  same  effect. 

For  example,  in  Figure  @NumberOf(alert-win),  when  the  user  makes  a  selection 
and  pushes  the  Quit  button,  filer  displays  a  pop-up  asking  for  confimiation.  All 
input  is  directed  into  this  confirmer,  and  the  user  is  forced  to  either  accept  the 
deletion  by  selecting  Yes  or  cancel  it  by  selecting  No  : 


Note  that  while  WIN_SHOW  defaults  to  TRUE  for  base  frames,  it  defaults  to  FALSE  for  subframes.  The 
same  holds  for  FRAME_SHOW_LABEL. 

1^  Note  that  the  subframe  won’t  actually  be  displayed  until  control  is  returned  to  the  Notifier. 
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Figure  4-7  Pop-up  Confirmer 


[List  Directory]  [Set  Is  flags!  [Edit]  [Delete] 


Filing  Mode:  i^Use  "File:"  item 

Directory:  /usr/view/1.75/usr/src/usr.bin/sunHindows/suntoo 1/examples 
File: 


apia%  Is 
Makefile 

Makef i le . customer 
Makefile.doc 
Makefile. old 

sccse 

addnewtest* 
addnewtest . c 
amimatecolor* 
animatecolor. 
bounce* 
bounce. c 
canvas_lnput* 
canvas_input.c 
canvas ^repaint* 
canvas .repaint .  c 
coloredit* 

I  CO lor edit. c 
,,.,conf  Irm.c 
®llapia!fe  0 


detool* 

dctool.c 

err 

filer* 
•pTlor  <- 


menugenproc . c 
resize.demo* 
resize.demo.c 
seln_deTno* 


Are  you  sure  you  want  to  Quit? 


[Cancel] 


image_browser_2* 
image_browser_2 . c 
loopback* 
loopback. c 
menugenproc* 


tty.io.c 

typein* 

typein.c 


window_loop  The  display  of  a  non-blocking  pop-up  is  controlled  using  the  WlN_SHOW  attri¬ 

bute.  The  display  of  a  blocking  pop-up,  on  the  other  hand,  is  controlled  with  the 
two  functions  window_loop  ( )  and  window_return  ( ) . 

caddr_t 

window_loop (subframe) 

Frame  subframe; 


void 

window_return (return_value) 
caddr  t  return  value; 


window_loop  ( )  causes  the  pop-up  to  be  displayed  and  receive  all  input 
directed  to  the  screen.  The  call  will  not  return  until  window_return  { )  is 
called  from  one  of  the  pop-up’s  notify  procedures.  The  value  passed  to 
window_return  ( )  as  return_value  wiU  be  returned  by 
window_loop  ( ) .  Its  interpretation  is  up  to  the  application.  That  is,  it  may  be 
used  to  indicate  whether  the  command  was  confirmed,  whether  a  valid  file  name 
was  entered,  and  so  on. 
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Restrictions  on  Pop-Up  Frames 


There  are  some  restrictions  on  pop-up  frames  displayed  using 
window_loop ( ) : 

□  You  can  only  have  one  subwindow  in  the  pop-up  frame. 

o  The  only  subwindow  types  that  work  properly  are  canvases  and  panels. 

These  limitations  do  not  apply  to  non-blocking  pop-ups  displayed  using 
WIN  SHOW. 


Controlling  a  Pop-up  or  Sun’s  convention  is  that  only  transient  items  such  as  pop-ups  have  shadows. 

Frame’s  Shadowing  However,  using  the  attribute  frame_S H0W_S HADOW  you  may  control  the  sha¬ 

dowing  effect  of  a  frame  or  a  subframe: 

□  If  you  want  your  base  frame  to  have  a  shadow,  then  set  the  attribute 
FRAME_SHOW_S HADOW  tO  TRUE. 

□  You  may  stop  a  shadow  from  appearing  with  a  sub_frame  during  create  time 
by  setting  FRAME_S HADOW  to  FALSE. 
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4.6.  Example  s — 

image _browser_l 


Figure  4-8  illustrates  how  to  specify  the  size  and  position  of  subwindows  in  order 
to  get  the  layout  that  you  want  This  application  lets  the  user  view  the  images  in 
files  generated  by  iconedit .  The  user  first  presses  the  List  button  to  get  a  list¬ 
ing.  The  user  then  selects  a  file  that  contains  an  image  and  press  the  Show  but¬ 
ton  to  view  the  image: 


Figure  4-8  image J)rowser_l 


Inage.brouser 


flame. Icon 
hellQ.uorld.icon 
helper. Icon 
home. Icon 
stop. Icon 

sunvi eu.manual . 1  con 

Morld.lcon 

coral%  Is  -1  *.1con 


hi  1 1 . 1  con 


book. icon  \ 
bulb. Icon 
cloun.lcon 
flame. Icon 
hello.uorld.l con 
helper. Icon 
home. Icon 
stop. Icon 

Isunv1eu_manual  .icon 
piorld.icon 
coral®! _ 


Dir: 

File:  *.1001;^ 

[List]  (Show)  [Quit] 


This  example  presents  a  somewhat  more  complex  subwindow  layout:  the  tty 
subwindow  has  been  moved  to  the  left,  the  control  panel  to  the  upper  right,  and  a 
panel  for  displaying  the  image  added  on  the  lower  right. 

Specifying  Subwindow  Size  "  You  can  specify  the  size  of  a  subwindow  either  in  pixels,  with  WIN_HE  IGHT 

and  WIN_WIDTH  or  in  terms  of  rows  and  columns,  with  WIN_R0WS  and 
WIN_C0LUMNS.^^  If  its  dimensions  are  not  specified,  then  a  subwindow  will 
extend  in  the  y  direction  to  the  bottom  edge,  and  in  the  x  direction  to  the  right 
edge  of  the  frame.  In  this  case  the  subwindow’s  height  and  width  will  have  the 
special  value  WIN_EXTEND_T0_EDGE,^‘^  and  wiU  track  the  edge  of  the  frame 
at  run  time,  expanding  or  shrinking  appropriately  when  the  user  resizes  the 
frame. 

Keep  in  mind  that  if  you  alter  the  size  of  a  frame  so  that  it  exactly  borders  on  a 
subwindow  by  calling  window_f  it  () ,  the  dimension  of  the  subwindow  that 
touches  the  frame  wiU  automatically  become  WIN__EXTEND_tO_EDGE. 


Row/colunm  space  is  discussed  in  the  next  example. 

It  is  meaningless  to  set  the  width  or  height  of  a  frame  to  WIN  EXTEND  TO  EDGE,  and  it  will  interfere 
with  subwindow  behavior. 
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Default  Subwindow  Layout 


Explicit  Subwindow  Layout 


The  default  subwindow  layout  algorithm  is  simple.  The  first  subwindow  is 
placed  at  the  upper  left  comer  of  the  frame  (leaving  space  for  the  frame’s  header 
and  a  border).  If  the  width  of  the  previously-created  subwindow  is  fixed,  not 
extend-to-edge,  then  the  next  subwindow  is  placed  to  the  right  of  it.  If  the  width 
of  the  previously-created  subwindow  is  extend-to-edge,  then  the  next  subwindow 
is  placed  below  it,  at  the  left  of  the  frame. 

This  default  layout  algorithm  handles  only  very  simple  topologies.  SunView 
provides  attributes  that  allow  you  to  specify  more  complex  layouts  by  explicitly 
positioning  subwindows.  You  can  position  one  subwindow  relative  to  another  by 
using  WIN_BEL0W  and  WIN_RIGHT_0F.  These  attributes  take  as  their  value 
the  handle  of  the  subwindow  you  want  the  new  subwindow  to  be  below  or  to  the 
right  of. 

image _browser_l,  pictured  on  the  preceding  page,  illustrates  the  use  of 
window_f  it  ( )  along  with  explicit  subwindow  positioning  to  obtain  a  particu¬ 
lar  layout.  The  relevant  calls  are  shown  below: 

- - - —  , 

tty  =  window_create (frame,  TTY, 

WIN_ROWS,  20, 

WIN_COLUMNS,  30, 

0); 

control_panel  =  window_create (frame,  PANEL,  0); 

(create  panel  items...) 

window_fit (control_panel) ; 

di splay_panel  =  window_create (frame,  PANEL, 

WIN_BELOW,  control_jpanel , 
WIN_RIGHT_OF,  tty, 

0); 

window  fit (frame) ; 


First  the  tty  subwindow  is  created  with  a  fixed  height  and  width.  Then  the  con¬ 
trol  panel  is  created,  with  no  specification  of  origin  or  dimensions. 

Since  the  width  of  the  previous  subwindow  was  fixed,  the  control  panel  is  placed 
by  default  just  to  the  right.  After  its  items  are  created,  the  control  panel  is  shrunk 
around  its  items  in  both  dimensions  with  window_f  it  ( ) . 

Next,  the  display  panel  is  created  and  explicitly  positioned  below  the  control 
panel  and  to  the  right  of  the  tty  subwindow.  Both  dimensions  of  the  display 
panel  default  to  win_extend_to_edge. 

Finally,  window  f  it  ( )  is  called  to  shrink  the  frame  to  the  height  of  the  tty 
window  and  the  combined  width  of  the  tty  window  and  the  control  panel. 


window  fit()  causes  the  window  to  shrink  until  it  encounters  the  first  fixed  border.  Subwindows 
which  are  extend-to-edge  don’t  stop  the  shrinking. 
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NOTE  One  thing  to  watch  out  for  is  that  WlN_BELOW  only  affects  the  subwindow’s  y 

dimension,  and  WIN_RIGHT_0F  only  affects  the  x  dimension. 

You  can  also  specify  the  origin  of  a  subwindow  in  pixels  using  WIN_X  and 
WIN_Y.  The  computations  for  these  attributes  take  the  borders  and  header  of  the 
frame  into  account,  so  that  specifying  WIN_X  and  WIN_Y  of  0  will  then  result  in 
the  subwindow  being  placed  correctly  at  the  upper  left  comer  of  the  frame. 

The  program  resize  demo,  listed  in  Appendix  A,  uses  these  attributes  to  lay  out 
its  subwindows  in  a  non-standard  manner. 

If  you  programmatically  change  the  size  or  position  of  subwindows  after  you 
create  them,  then  you  must  explicitly  re-specify  the  origin  of  any  subwindows 
that  are  below  or  to  the  right  of  the  altered  subwindows.  This  must  be  done  even 
if  you  specified  the  positions  of  these  ofiier  subwindows  using  relative  position 
attributes,  such  as  WIN_BEL0W, 

This  step  is  necessary  because  subwindows  are  not  automatically  laid  out  again 
when  the  positions  and  sizes  of  other  subwindows  are  changed.  They  are  only 
laid  out  again  if  the  frame  changes  size.  When  re-specifying  the  layout  of  the 
other  subwindows,  you  can  use  relative  position  attributes  such  as  win_below. 

The  Rect  Structure  The  attributes  WlN_x,  WIN_Y,  WIN_WIDTH  and  WIN_HEIGHT,  taken  together, 

define  the  rectangle  occupied  by  a  window.  This  rectangle  is  actually  stored  as  a 
Rect  stmct,  which  you  can  get  or  set  using  the  attribute  WIN_RECT.  The 
definition  of  a  Rect,  found  in  <sunwihdow/rect .  h>,  is:^^ 

typedef  struct  rect  { 
short  r_left; 
short  r_top; 
short  r_width; 
short  r_height; 

}  Rect ; 


Changing  Subwindow  Layout 
Dynamically 


Specifying  Subwindow  Sizes 
and  Positions 


The  Rect  is  the  basic  data  stmcture  used  in  SunView  window  geometry.  Where 
complex  shapes  are  required,  they  are  built  up  out  of  groups  of  rectangles. 


The  result  that  a  window  returns  is  relative  to  a  frame’s  positioning  space.  It  is  not  self-relative  and  it  is 
not  parant-relative.  Therefore,  WIN_RECT  should  only  be  used  for  window  positioning  operations.  Do  not  use 
itforpw_lock(). 

For  a  detailed  discussion  of  rectangle  geometry,  induding  useful  macros  for  operating  on  rectangles,  see 
the  chapter  entitled  Rects  and  Realists  in  the  SunView  1  System  Programmer’s  Guide. 
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4.7.  Example  6 — 

image_browser_2 


In  the  next  example,  when  the  user  specifies  a  filename  and  pushes  Browse  the 
images  in  the  files  are  displayed  in  a  scrollable  panel: 


Figure  4-9  image J)rowser_2 


inat|e_broiiiser_2 


D1r:  /usr/v1ew/iIoc/app/co(Je  [Brousej 
Fila:  ♦.icot^  [  quit  ) 


The  point  of  this  example  is  to  illustrate  how  you  can  use  row! column  space  to 
specify  the  size  of  a  subwindow.  The  goal  was  to  make  the  panel  just  the  right 
size  to  display  a  single  page  of  icons,  with  four  rows,  four  columns,  and  10  pixels 
of  white  space  around  each  icon. 

Row/Column  Space  Row/column  space  refers  to  a  logical  grid  defining  the  rows  and  columns  of  a 

window.  You  can  define  the  row/column  space  for  a  window  by  using  the  attri¬ 
butes  in  the  following  table: 

Table  4-2  Window  Row! Column  Geometry  Attributes 


Attribute 

Description 

Default 

Def.  in  Panels 

WIN  BOTTOMMARGIN 

Bottom  margin. 

0 

(same) 

WIN  COLUMN  GAP 

Space  after  columns. 

0 

(same) 

WIN  COLUMN_WIDTH 

Width  of  a  column. 

Width  of  WIN_FONT. 

(same) 

WIN  LEFT  MARGIN 

Left  margin. 

5 

4 

WIN  RIGHTMARGIN 

Right  margin. 

5 

0 

WIN  ROW  GAP 

Space  after  rows. 

0 

5 

WIN  ROW  HEIGHT 

Height  of  a  row. 

Height  of  WIN  FONT 

(same) 

WIN  TOP  MARGIN 

Top  margin. 

519 

4 

19  In  frames  with  headers,  the  default  for  WIN_TOP_MARGIN  depends  on  the  system  font.  With  the  default 
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Defining  a  Panel’s  Row/Column  Using  the  row/column  space  attributes,  the  icon  browsing  panel  pictured  on  the 
Space  preceding  page  is  specified  as  follows: 


Scrollbar  scrollbar  =  scrollbar_create (SCROLL  MARGIN,10,0); 
bar_width  =  (int) scrollbar_get (scrollbar,  SCROLL  THICKNESS,  0); 

display_panel  =  window  create (base 

_frame,  PANEL, 

WIN_VERTICAL  SCROLLBAR,  scrollbar. 

WIN_ROW  HEIGHT, 

64, 

WIN_COLUMN_WIDTH, 

64, 

WIN_ROW_GAP , 

10, 

WIN_COLUMN_GAP , 

10, 

WIN_LEFT_MARGIN , 

bar  width  +10, 

WIN_TOP_MARGIN , 

10, 

WIN_ROWS, 

4, 

WIN_COLDMNS, 

0); 

4, 

window_set (display_panel,  WIN  LEFT 

MARGIN,  10,  0); 

This  achieves  our  goal  of  a  panel  the  right  size  for  a  4x4  array  of  64  pixel  square 
icons,  with  10  pixels  of  white  space  around  each  icon. 


Positioning  Panel  Items  in  Once  you  have  defined  your  row/column  space,  you  can  position  panel  items 

Row/Column  Space  within  that  space  with  the  ATTR_ROW  ( )  and  ATTR_col  ( )  macros.^®  The  code 

fragment  shown  below  shows  how  the  items  for  the  browsing  panel  are  created 
and  positioned  at  the  proper  row  and  column  each  time  the  Browse  button  is 
pushed: 

' - — - — N 

for  (row  =  0,  iniage_count  =  0;  image_count  <  files_count;  row++) 
for  (col  =  0;  col  <=  4  &&  image_count  <  files_count;  col++)  ( 
if  (image  =  get_image (image_count) )  { 

panel_crGate_item(display_panel,  PANEL_MESSAGE, 

PANEL_ITEM_y ,  ATTR_ROW ( row) , 

PANEL_ITEM_X ,  ATTR_COL ( col ) , 

PANEL_LABEL_IMAGE,  image,  0) ; 

image_count ++ ; 

} 

} 

V - - - , 


This  example  is  complicated  somewhat  by  an  inconsistency  in  the  way  margins 
are  handled  in  the  current  release  of  SunView.  The  left  and  top  margins  are  used 
in  two  ways:  for  determining  the  size  of  the  panel,  and  for  determining  the  loca¬ 
tion  of  panel  items  positioned  with  ATTR_COL  ( )  and  ATTR_ROW  ( } .  The  size 
computation  does  not  take  into  account  any  scrollbar  which  may  be  present;  the 
positioning  computation,  on  the  other  hand,  does  take  the  scrollbar  into  account. 
That  is  why,  in  the  call  to  window_create  { )  above,  WIN_LEFT_MARGIN  is 
set  to  the  width  of  the  scrollbar  plus  10  pixels,  and  then  set  immediately  after¬ 
ward  to  10  pixels. 

system  font,  it  defaults  to  17. 

^  These  “character  unit  macros”  are  described  fuUy  in  Chapter  1 8,  Attribute  Utilities. 
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4.8.  Attribute  Ordering  The  general  rule  is  that  attributes  in  SunView  are  evaluated  in  the  order  they  are 

given.  The  following  two  examples  of  text  subwindow  calls  illustrate  how  giv¬ 
ing  the  same  attributes  in  different  orders  can  produce  different  effects: 

window_set (textsw,  TEXTSW_FILE,  0); 

window_set (textsw,  TEXTSW_FIRST,  20,  TEXTSW_FILE,  0); 

window_set  (textsw,  TEXTSW_FIIjE,  0); 

window_set (textsw,  TEXTSW_FILE,  "file_2",  TEXTSW_FIRST,  20,  0)  ; 

In  the  first  pair  of  calls,  the  index  is  first  set  to  the  20th  character  of  f  ile_l, 
then  f  ile_2  is  loaded,  starting  at  character  zero.  The  second  pair  of  calls  first 
loads  f  i  1  e_2 ,  then  sets  the  index  in  f  i  1  e_2  to  20. 

Command-line  Arguments  The  attribute  FRAME_ARGS  bears  special  mention.  As  described  in  the  second 

example  in  this  chapter,  simple  jpaneU  this  attribute  causes  the  frame  to  process 
the  command-line  arguments  given  by  the  user  at  run  time.  Some  of  these  argu¬ 
ments  correspond  to  attributes  that  can  be  set  programmatically;  for  example,  - 
Wh  corresponds  to  W  IN_ROW S 

The  basic  rule,  that  attributes  are  evaluated  in  the  order  given,  applies  equally  to 
attributes  that  are  explicitly  specified  in  the  program  and  to  those  that  are 
specified  at  run  time  using  their  command-line  equivalents.  If  a  given  attribute  is 
specified  more  than  once,  then  the  last  setting  is  the  one  that  takes  effect.  You 
can  therefore  control  whether  your  application  or  the  user  has  the  last  word  by 
specifying  attributes  after  or  before  FRAME_ARGS. 

Let’s  take  a  couple  of  examples: 

window_create (0,  FRAME, 

FRAME_ARGS ,  a rgc ,  a r gv , 

FRAME_LABEL,  "LABEL  FROM  PROGRAM", 

WIN_ROWS,  10, 

0); 

window_create ( 0 ,  FRAME, 

FRAME_LABEL,  "LABEL  FROM  PROGRAM", 

WIN_ROWS,  10, 

FRAME_ARGS,  argc,  argv, 

0); 

Assume  that  the  program  was  invoked  with  a  command  line  containing  the  fol¬ 
lowing  arguments: 

-Wl  "LABEL  FROM  COMMAND-LINE"  -Wh  4 

In  the  first  call,  by  putting  FRAME_ARGS  at  the  start  of  the  list,  the  application 
overrides  the  command-line  arguments,  and  guarantees  that  the  frame  header  will 
read  “LABEL  FROM  PROGRAM”  and  the  height  will  be  10  lines. 


^  For  a  complete  list  of  these  ai^uments  see  the  Command.  Line  Frame  Arguments  table  in  Chapter  19, 
SunView  Interface  Summary. 
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In  the  second  caU,  since  FRAME_ARGS  appears  at  the  end  of  the  list,  the 
command-line  arguments  override  what  the  application  has  specified,  resulting  in 
a  label  of  “LABEL  FROM  COMMAND-LINE”  and  a  height  of  4  lines. 


Keep  in  mind  that  if  you  specify  WlN_FONT,  it  does  not  override  the  font  that 
the  user  specified  using  -Wt. 


Different  Classes  of  Attributes  hi  the  case  of  different  objects,  the  window  attributes  (those  beginning  with 

WIN_)  are  processed  after  the  others  (frame_*,  PANEL_*,  and  so  on). 

Suppose  that  you  want  to  create  a  canvas  with  a  scrollbar.  You  also  want  the 
logical  canvas  to  expand  when  the  user  makes  the  window  bigger,  but  never  to 
shrink  past  its  initial  size,  even  if  the  user  shrinks  the  window.  The  initial  size  of 
the  canvas  should  be  the  size  of  the  “inner”  portion  of  the  window  —  not  includ¬ 
ing  the  scrollbar. 

The  straightforward  approach  would  be  to  simply  set  aU  relevant  attributes  when 
the  window  is  created,  as  in: 


o 

Since  the  window  attributes  are  evaluated  after  the  canvas  attributes,  the  canvas 
size  is  set  according  to  the  initial  size  of  the  window,  which  does  not  have  a 
scrollbar.  By  the  time  WIN_VERTICAL_SCR0LLBAR  is  evaluated,  the  canvas 
refuses  to  shrink  to  the  smaller  inner  portion  of  the  window,  since 
CANVAS_AUTO_SHRlNK  has  already  been  evaluated  and  set  to  FALSE. 

In  general,  you  can  force  a  particular  order  of  evaluation  by  using  separate 
window  set  ( )  caUs,  as  in: 


canvas  =  window_crGate (frame,  CANVAS, 

WIN_VERTICAL_SCROLLBAR,  scrollbar_create (0) , 
0); 

window_set (canvas,  CANVAS_AUTO_SHRINK,  FALSE,  0); 

V _ _ _ J 


-N 

canvas 

=  window_create (frame,  CANVAS, 

WIN_VERTI CAL_SCROLLBAR , 

scrollbar  create (0), 

CANVAS  AUTO  SHRINK, 

FALSE, 

0); 

1 

_ i 

This  call,  however,  results  in  a  canvas  which  is  too  big,  extending  underneath  the 
vertical  scrollbar.  This  is  because  of  the  order  in  which  the  CANVAS_  and  WIN_ 
attributes  are  evaluated. 


The  Panel  Package 


The  panel  package  deviates  from  the  norm  in  that  its  attributes  are  generally  not 
order-dependent  For  example,  you  can  specify  the  label  of  an  item  before  the 
font,  and  the  font  will  be  used  even  though  it  appears  after  the  label. 

The  only  thing  to  watch  out  for  is  that  you  can’t  change  the  font  in  a  single  call, 
as  in: 


o 
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panel  set (text_item. 

PANEL  FONT, 

font_l. 

PANEL  LABEL_STRING, 

"Label:", 

PANEL  FONT, 

font__2. 

PANEL  VALUE, 

"initial  value". 

0); 

_ / 

The  above  call  will  cause  both  the  label  and  the  value  for  text_item  to  be  ren¬ 
dered  in  font  2. 


4.9.  File  Descriptor  Usage  In  SunView,  each  window  is  actually  a  device,  /  dev/winnnn,  that  is  accessed 

through  a  file  descriptor.  Other  packages  such  as  the  selection  service  also  use 
file  descriptors.  In  SunOS  there  is  a  limit  to  the  number  of  file  descriptors  one 
program  can  have  open;  in  Release  4.0  it  is  64.  Thus  it  is  possible  for  your  appli¬ 
cation  to  run  out  of  file  descriptors. 

The  following  table  summarizes  how  file  descriptors  are  used  in  SimView. 

Table  4-3  SunView  File  Descriptor  Usage 


Window  Type! 
Package 

FD  Usage 

How  FDs  are  used 

FRAME 

1 

1  for  the  window. 

CANVAS 

1 

1  for  the  window. 

TEXTSW 

3 

1  for  the  window, 

+  1  for  the  file  to  be  edited  (if  any), 

+  1  for  scratch  (the  /tmp/Text...  file). 

(2) 

2  temporarily  created  during  a  save. 

PANEL 

1 

1  for  the  window. 

TTYSW 

2 

1  for  the  window, 

-1- 1  for  the  pty  (pseudo-tty). 

MENU 

0 

Fullscreen  access  uses  the  window’s  FD. 

ALERT 

1 

1  for  positioning 

Alerts  have  a  frame  and  a  panel; 
however,  the  FDs  are  allocated  for  the 
first  alert  and  reused  by  subsequent  alerts. 

Pointer 

0 

Most  pointers  are  managed  by  the  kernel. 

Icon 

0 

Frame  uses  same  FD  whether  open  or  iconic. 
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Table  4-3 


SunView  File  Descriptor  Usage —  Continued 


Window  Type! 
Package 

FD  Usage 

How  FDs  are  used 

Scrollbar 

0 

(implemented  as  a  region  —  read  the 

SunView  System  Programmer’s  Guide) 

window  manager 

(1) 

1  temporarily  used  for  window 
management  operations. 

UNIX 

3 

stdin/stdout/stderr 

framebuffer 

1 

frame  buffer  FD  gets  allocated 
automatically  with  the  base  frame.  The  screen 
device  must  be  opened  for  your  program 
to  draw  on  it. 

Selection  Service 

3 

selection  service  fd’s 
are  allocated  whenever  there  is  something 
that  will  set  or  get  from  the  selection 
service.  For  example,  if  you  put  in 
selection  service  code  or  the  first  time 
a  panel  item  is  allocated. 

(1) 

This  uses  sockets  to  communicate: 

1  for  the  connection  to  the  service 
+  1  to  receive  UDP  requests 
+  1  TCP  rendezvous  socket  for  transfers. 

1  transiently  opened  when  a  transfer 
is  in  progress  to  carry  it. 

G 
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Canvases 


The  most  basic  type  of  subwindow  provided  by  SunView  is  the  Canvas.  A  can¬ 
vas  is  essentially  a  window  into  which  you  can  draw. 

For  a  demonstration  of  the  various  canvas  attributes,  run  the  program 
/usr/demo/canvas_demo.  For  examples  of  canvases  that  illustrate  event 
handling,  run  the  image  editor  iconedit(l).  iconedit  uses  two  canvases, 
the  large  drawing  canvas  on  the  left,  and  the  small  proof  area  on  the  lower  right. 

In  order  to  use  canvases  you  must  include  the  header  file 
<suntool/canvas .h>. 


Summary  Listing  and  Tables 


To  give  you  a  feeling  for  what  you  can  do  with  canvases,  the  following  page  lists 
the  available  canvas  attributes,  functions  and  macros.  Many  of  these  are  dis¬ 
cussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to  check).  All  are 
briefly  described  with  their  arguments  in  the  canvas  summary  tables  in  Chapter 
19,  SunView  Interface  Summary: 

□  the  Canvas  Attributes  table  begins  on  page  319; 

□  the  Canvas  Functions  and  Macros  table  begins  on  page  320. 
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_ _ Canvas  Attributes _ 

CANVAS_ADTO_CLEAR  CANVAS_FIXED_IMAGE  CANVAS_REPAINT_PROC 

CANVAS_AUTO_EXPAND  CANVAS_HEIGHT  CANVAS_RESIZE_PROC 

CANVAS_AUTO_SHRINK  CANVAS_MARGIN  CANVAS_RETAINED 

CANVAS  FAST_MONO  CANVAS_PIXWIN  CANVAS_WIDTH 


Canvas  Functions  and  Macros 

canvas  event (canvas,  event) 
canvas  pixwin (canvas) 

can vas_window_e vent (canvas,  event) 
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5.1.  Creating  and  Drawing  Like  all  windows  in  SunView,  canvas  subwindows  are  created  with 

into  a  Canvas  window_create  ( ) .  When  drawing  into  a  canvas  use  the  canvas  pixwin, 

which  you  can  get  with  the  canvas_pixwin  { )  macro. 

The  pixwin  is  the  structure  through  which  you  render  images  in  a  window.  You 
draw  points,  lines  and  text  on  a  pixwin  with  a  set  of  functions  of  the  form 
pw_*  { }  —  pw_wr  ite  { ) ,  pw_vector  ( ) ,  pw_text  ( }  etc.^^ 

Example  1 :  As  a  beginning  example,  the  following  program  puts  up  a  canvas  containing  a 

box  with  the  words  “Hello  World!”: 

- - ; - 

♦include  <suntool/sunview.h> 

♦include  <suntool/canvas .h> 

main (argc,  argv) 
int  argc; 
char  **argv; 

{ 

Frame  frame; 

Canvas  canvas; 

Pixwin  *pw; 

/*  create  frame  and  canvas  */ 

frame  =  window_create (NULL,  FRAME,  0); 

canvas  =  window_create (frame,  CANVAS,  0); 

/*  get  the  canvas  pixwin  to  draw  into  */ 
pw  =  canvas_j3ixwin  (canvas)  ; 

/*  draw  top,  bottom,  left,  right  borders  of  box  */ 


pw_vector (pw. 

100, 

100, 

200, 

100, 

PIX_ 

SRC, 

1); 

pw_vector (pw. 

100, 

200, 

200, 

200, 

PIX_ 

SRC, 

1); 

pw  vector (pw. 

100, 

100, 

100, 

200, 

PIX_ 

SRC, 

1); 

pw  vector (pw. 

200, 

100, 

200, 

200, 

pix' 

[sRC, 

1); 

/*  write  text  at  (125,150)  in  default  font  */ 
pw_text(pw,  125,  150,  PIX_SRC,  0,  "Hello  World !") ; 

window_main_loop (frame) ; 
exit (0) ; 

} 

V. _ / 


The  PIX_SRC  argument  to  pw_vector  ( )  and  pw_text  ( )  is  a  rasterop 
function  specifying  the  operation  which  is  to  produce  the  destination  pixel 
values.  There  are  several  other  rasterop  fimctions  besides  PIX_SRC;  they  are 
described  in  Chapter  2  of  the  Pixrect  R^erence  Manual. 


^  Pixwins  and  thdr  associated  functions  arc  covercd  in  detail  in  Chapter  7,  Imaging  Facilities:  Pixwins. 
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o 

5.2,  Scrolling  Canvases  Many  applications  need  to  view  and  manipulate  a  large  object  through  a  smaller 

viewing  window.  To  facilitate  this  SunView  provides  scrollbars,  which  can  be 
attached  to  subwindows  of  type  canvas,  text  or  panel. 

Example  2;  The  code  below  creates  a  canvas  that  is  scrollable  in  both  directions: 


( 

frame  =  window_create (NULL,  FRAME,  0) 
canvas  =  window_create (frame,  CANVAS, 

/ 

CANVAS_ADTO_SHRINK , 

FALSE, 

CANVAS  WIDTH, 

1000, 

CANVAS_HEIGHT, 

1000, 

WI N_VERTICAL_SCROLLBAR , 

scrollbar_create (0) , 

WIN  HORIZONTAL  SCROLLBAR, 
0); 

scrollbar_create (0)  , 

V _ 

_ 

NOTE 


The  distinction  between  the  dimensions  of  the  canvas  and  of  the  window  is 
important.  In  the  above  example,  we  set  the  canvas  width  and  height  to  1000 
pixels.  Since  the  dimensions  of  the  canvas  subwindow  (i.e.  win_width  and 
WIN_HEIGHT)  were  not  explicitly  set,  the  subwindow  extends  to  fill  the  frame. 
The  frame’s  dimensions,  in  turn,  were  not  explicitly  set,  so  it  defaults  to  25  lines 
by  80  characters  in  the  default  font  The  result  is  a  logical  canvas  roughly  the 
area  of  the  screen,  which  is  viewed  through  a  window  about  one  fourth  that  size. 

It  is  necessary  to  explicitly  (Usable  the  “auto-shrink"  feature  in  the  above  exam 
pie.  If  this  were  not  done,  the  canvas  size  would  be  truncated  to  the  size  of  the 
window.  See  Section  5.6,  Automatic  Sizing  cf  the  Canvas. 
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Canvas  Model 


The  components  of  a  canvas  subwindow  and  their  relationships  can  be  seen  in 
Figure  5-1. 


Figure  5-1  Canvas  Geometry 


Scrollbars 


CANVAS_WDTH 


(CANVAS_WIDTH-1, 

CANVAS_HEIGHT-1} 


The  Canvas 


The  Canvas  Pixwin 


Think  of  the  canvas  itself  as  a  logical  surface  on  which  you  can  draw.  The  width 
and  height  of  the  canvas  are  set  via  the  attributes  CANVAS_WIDTH  and 
CANVAS_HEIGHT.  So  the  coordinate  system  is  as  shown  in  Figure  5-1,  with  the 
origin  at  the  upper  left  comer  and  the  point  (CANVAS_WIDTH-1, 
CANVAS_HEIGHT-1)  at  the  lower  right  comer.  Note  that  the  logical  canvas 
origin  is  always  at  (0, 0). 

As  mentioned  above,  you  draw  on  the  canvas  by  writing  into  the  canvas  pixwin, 
which  is  retrieved  via  the  CANVAS_pixwin  attribute  or  the 
canvas_pixwin  ( }  macro. 

The  canvas  pixwin  is  set  up  to  take  scrolling  into  account  by  performing  the 
transformation  from  your  canvas  coordinate  system  to  its  pixwin  coordinate  sys¬ 
tem.  So  when  you  draw  into  the  canvas  pixwin  using  the  pw_*  functions  you 
don’t  have  to  do  any  mapping  yourself  —  the  arguments  you  give  should  be  in 
the  canvas  coordinate  system. 

Between  the  frame  border  and  the  canvas  pixwin  is  a  margin,  set  via  the  attribute 
CANVAS_MARGIN.  This  margin  defaults  to  zero  pixels,  so  in  the  simple  case, 
the  canvas  pixwin  occupies  the  entire  inner  area  of  the  window  pixwin.  If  one  or 
more  scrollbars  are  present,  the  canvas  margin  begins  at  the  inside  border  of  the 
scrollbar. 

Note  the  distinction  between  the  pixwin  of  the  canvas  (attribute 
CANVAS_P  ixwiN)  and  the  pixwin  of  the  window  (attribute  wiN_p  ixwiN), 
The  canvas  pixwin  is  one  of  several  regions  of  the  window’s  pixwin,  which  also 
includes  the  regions  occupied  by  the  scrollbars  and  the  margin. 
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5.4.  Repainting 


Retained  Canvases 


Non-Retained  Canvases 


The  Repaint  Procedure 


The  canvas  package  manages  the  canvas  pixwin  for  you.  In  particular,  the  clip¬ 
ping  list  is  restricted  to  the  area  of  the  canvas  pixwin  actually  backed  by  the  can¬ 
vas.  This  means  that  you  can  never  draw  off  toe  edge  of  the  canvas.  For  exam¬ 
ple,  if  you  have  set  the  canvas  height  to  be  less  than  the  height  of  the  canvas 
pixwin,  any  pw_*  operations  that  attempt  to  draw  below  the  canvas  height  will 
be  clipped  away. 

By  default,  canvases  are  retained —  i.e.  the  canvas  package  maintains  a  copy  of 
the  bits  on  the  screen  in  a  backing  pixrect,  from  which  it  automatically  repaints 
the  screen  image  when  necessary.  If  you  wish  to  handle  repainting  yourself,  you 
can  defeat  this  feature. 

The  canvas  package  allocates  a  backing  pixrect  the  size  of  the  logical  canvas. 
When  the  canvas  width  or  height  changes,  a  new  backing  pixrect  of  the  proper 
dimensions  is  allocated,  the  contents  of  the  old  pixrect  are  copied  into  the  new 
pixrect,  and  the  old  pixrect  is  freed. 

For  a  non-retained  canvas,  set  CANVAS_RETAINED  to  FALSE,  and  give  your 
own  repaint  function  as  the  value  of  CANVAS_REPAlNT_PROC. 

The  repaint  procedure  is  called  whenever  some  part  of  the  canvas  has  to  be 
repainted  onto  the  canvas  pixwia  Note  that  if  you  supply  a  repaint  proc,  it  wUl 
be  called  even  if  the  canvas  is  retained  —  i.e.  the  canvas  package  will  not 
automatically  copy  from  the  backing  pixrect  to  the  canvas  pixwin. 

The  form  of  the  repaint  procedure  is: 

sample_repaint_p roc (canvas,  pixwin,  repaint_area) 

Canvas  canvas; 

Pixwin  *pixwin; 

Rectlist  *repaint_area; 

The  first  two  arguments  are  die  canvas  and  its  pixwin  (i.e.  the  value  of 
canvas  j)ixwin  (canvas) ).  The  third  argument,  repaint_area,  is  a 
pointer  to  a  list  of  rectangles  (type  Re  ct  li  st  *)  which  define  the  area  to  be 
painted.^^ 

Before  the  canvas  package  calls  your  repaint  procedure,  it  restricts  the  clipping 
list  to  the  area  which  needs  to  be  painted.  Thus  if  your  application  is  not  capable 
of  repainting  arbitrary  areas  of  the  canvas  you  can  repaint  the  entire  image 
without  worrying  about  excessive  repainting. 

If  you  choose  not  to  redraw  each  individual  rect  in  the  repaint  area,  you  can  use 
the  rectangle  given  by  repaint_area->r  l_bound,  which  is  the  bounding 
rectangle  for  the  repaint  area. 

Note  that  if  the  attribute  CANVAS_auto_CLEAR  is  TRUE,  the  canvas  package 
wiU  clear  the  repaint  area  before  calling  your  repaint  procedure. 


^  Rectlists  arc  covercd  in  detail  in  the  chapter  on  Reels  and  Rectlists  in  the  SunView  1  System 
Programmer's  Guide. 
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A  retained  canvas  has  two  advantages.  First,  the  repainting  will  be  faster  since  it 
is  a  simple  block  copy  operation.  Second,  it  eliminates  the  need  for  the  applica¬ 
tion  to  keep  a  display  list  from  which  to  regenerate  the  image. 

On  the  other  hand  there  is  a  performance  penalty  on  writing,  since  each  operation 
is  performed  both  on  the  canvas  pixwin  and  the  backing  pixrect.  This  penalty 
may  be  reduced  by  using  the  pw_bat  ch  ( )  caU  described  in  the  chapter  entitled 
Imaging  Facilities:  Pixwins. 

The  client’s  resize  procedure  is  called  whenever  the  canvas  width  or  height 
changes.  Its  form  is: 

sample_resize_j)roc  (canvas,  width,  height) 

Canvas  canvas; 

int  width; 

int  height; 

NOTE  You  should  never  repaint  the  image  in  the  resize  procedure,  since  if  there  is  any 
new  area  to  be  painted,  the  repaint  procedure  will  be  called  later. 

There  are  some  subtle  points  to  be  aware  of  related  to  whether  or  not  the  image  is 
fixed  size  (CANVAS_fixed_image  is  true).  In  the  default  case  the  image  is 
fixed  size,  and  the  repaint  procedure  will  not  be  called  when  the  canvas  gets 
smaller,  since  there  will  be  no  new  canvas  area  to  be  repainted.  If  the  image  is 
not  fixed  size,  then  whenever  the  canvas  size  changes,  the  canvas  package 
assumes  that  the  entire  canvas  needs  to  be  repainted,  and  the  repaint  area  will 
contain  the  entire  canvas. 

Initializing  a  Canvas  Neither  the  repaint  procedure  nor  the  resize  procedure  will  be  called  until  the 

canvas  subwindow  has  been  displayed  at  least  once.  This  allows  you  to  create 
and  initialize  a  canvas  without  having  to  deal  with  the  resize/repaint  procedures. 
The  very  first  time  the  canvas  is  displayed,  the  resize  procedure  will  be  called 
with  the  current  canvas  size.  This  initial  call  to  the  resize  procedure  allows  you 
to  synchronize  with  the  canvas  size. 


Retained  vs.  Non-Retained 


5.5.  Tracking  Changes  in 
the  Canvas  Size 
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Example  3: 


The  canvas  in  the  program  below  has  a  repaint  procedure  which  fills  the  canvas 
with  an  appropriately  sized  rectangle  and  diagonals. 


tinclude  <suntool/sunview,h> 
#include  < sunt ool/ can va s .h> 


static  void  repaint_canvas {) ; 

main (argc,  argv) 
int  argc; 
char  **argv; 

{ 

Frame  frame; 


frame  =  window_create (NULL,  FRAME,  0); 
window_create (frame,  CANVAS, 

CANVAS_RETAINED,  FALSE, 

CANVAS_FIXED_IMAGE,  FALSE, 
CANVAS_REP AI NT_PROC ,  repa int_can vas , 
0); 

window_main_loop (frame) ; 
exit (0) ; 


static  void 

repaint_canvas (canvas,  pw,  repaint_area) 
Canvas  canvas; 

Pixwin  *pw; 

Rectlist  *repaint_area; 

{ 


int  width  =  (int) window_get (canvas, 

int  height  =  (int) window_get (canvas, 

int  margin  =  10; 

int  xleft  =  margin; 

int  xright  =  width  -  margin; 

int  ytop  =  margin; 

int  ybottom  =  height  -  margin; 


CANVAS_WIDTH) ; 
CANVAS_HEIGHT)  ; 


/*  draw  box  */ 

pw_vector (pw,  xleft,  ytop,  xright,  ytop,  PIX_SRC,  1); 
pw_vector (pw,  xright,  ytop,  xright,  ybottom,  PIX_SRC,  1) ; 
pw_vector (pw,  xright,  ybottom,  xleft,  ybottom,  PIX_SRC,  1); 
pw_vector (pw,  xleft,  ybottom,  xleft,  ytop,  PIX_SRC,  1) ; 

/*  draw  diagonals  */ 

pw_vector (pw,  xleft,  ytop,  xright,  ybottom,  PIX_SRC,  1); 
pw_vector (pw,  xright,  ytop,  xleft,  ybottom,  PIX_SRC,  1); 
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There  are  several  points  to  note  from  the  example  on  the  previous  page.  First, 
since  the  width  and  height  of  the  canvas  are  not  specified,  they  default  to  the 
width  and  height  of  the  window.  Second,  since  the  image  being  drawn  is  depen¬ 
dent  on  the  size  of  the  canvas,  we  set  CANVAS_fixed_image  to  false. 
Third,  when  the  repaint  proc  is  called,  we  don’t  bother  to  draw  the  specified 
repaint  area,  instead  we  rely  on  the  clipping  list  to  be  restricted  correctly  and 
simply  redraw  the  entire  image. 

5.6.  Automatic  Sizing  of  Two  attributes  requiring  some  explanation  are  CANVAS_AUTO_EXPAND  and 

the  Canvas  CANVAS_auto_SHRINK.  Setting  both  these  attributes  to  true  allows  you  to 

have  a  drawing  area  which  automatically  tracks  the  size  of  the  window. 

If  CANVAS_AUTO_EXPAND  is  TRUE,  the  canvas  width  and  height  are  never 
allowed  to  be  less  than  the  edges  of  the  canvas  pixwin.  For  example,  if  you  try  to 
set  CANVAS_WIDTH  to  a  value  which  is  smaller  than  the  width  of  the  canvas 
pixwin,  the  value  will  be  automatically  expanded  (rounded  up)  to  the  width  of 
the  canvas  pixwin. 

The  main  use  of  CANVAS_AUTO_EXPAND  is  to  allow  the  canvas  to  grow  bigger 
as  the  user  stretches  the  window.  For  example,  if  the  canvas  starts  out  exactly 
the  same  size  as  the  canvas  pixwin,  and  the  user  stretches  the  window,  the  canvas 
pixwin  will  get  bigger,  which  wiU  cause  the  canvas  itself  to  expand. 

Another  point  to  keep  in  mind  is  that  whenever  you  set 

CANVAS_AUTO_EXPAND  to  TRUE,  the  canvas  will  be  expanded  to  the  edges  of 
the  canvas  pixwin  (if  it  is  smaller  to  begin  with). 

CANVAS_AUTO_SHRiNK  is  Symmetrical  to  CANVAS_auto_expand.  If 
CANVAS_AUTO_SHRlNK  is  TRUE,  the  canvas  width  and  height  are  never 
allowed  to  be  greater  than  the  edges  of  the  canvas  pixwin. 

NOTE  Aj'  described  in  Section  4.8,  Attribute  Ordering,  the  canvas  attributes  are 

evaluated  before  the  generic  window  attributes.  This  means  that,  if  you  want  to 
set  the  window  size  and  then  disable  automatic  sizing  of  the  canvas,  you  must 
first  set  the  window  size,  then,  in  a  separate  window_set  ( )  call,  disable 
CANVAS_AUTO_S  BRINK  and/or  CANVAS_AUTO_EXPAND.  If  you  do  both  in 
the  same  call,  the  auto-sizing  will  be  turned  off  before  the  window  size  is  set,  so 
the  canvas  size  wiU  not  match  the  window  size  you  specify.  Here  is  an  example 
of  how  to  do  it  correctly: 

r -  ^ 

canvas  =  window_create (frame,  CANVAS, 

WIN_HEIGHT,  400, 

WIN_WIDTH,  600, 

0)  ; 

window_set (canvas, 

CANVAS_AUTO_SHRINK,  FALSE, 

CANVAS_AUTO_EXPAND,  FALSE, 

0); 

s _ ^ 
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5.7.  Handling  Input  in 
Canvases 


This  section  gives  some  hints  on  basic  handling  of  input  in  canvases.^** 


Default  Input  Mask  By  default,  canvases  enable  loc_WINENTER,  LOC_winexit,  L0C_M0VE  and 

the  three  mouse  buttons,  MS  LEFT,  MS  MIDDLE  and  MS  RIGHT.^^ 


NOTE  Since  the  canvas  pixwin  is  actually  a  region  of  the  subwindow's  pixwin,  your 
event  procedure  will  receive  LOC_RGNENTER  and  LOC_RGNEXIT  events 
rather  than  LOC_WINENTER  and  L0C_WINEXIT.  The  locator  motion  events 
—  LOC_MOVE,  LOC_STILL,  LOC_DRAG,  and  LOC_TRAJECTORY  —  will 
only  be  passed  to  your  event  procedure  if  they  faU  within  the  canvas  pixwin. 

You  can  enable  events  other  than  those  listed  above  with  the  window  attributes 
applying  to  events.  So,  for  example,  you  could  aUow  the  user  to  type  in  text  to  a 
canvas  by  calling: 

- 

window_set (canvas,  WIN_CONSOME_KBD_EVENT ,  WIN_ASCII_EVENTS,  0) ; 

ly _ ^ ^ ^ 

An  application  needing  to  track  mouse  motion  with  the  button  down  would 
enable  L0C_drag  by  calling: 

/  > 
window_set (canvas,  WIN_CONSUME_PICK_EVENT,  LOC_DRAG,  0) ; 

I - - 


If  you  supply  an  event  procedure  as  the  value  of  win_event_proc,  it  will  get 
called  when  any  event  is  received  for  the  canvas.  Before  your  event  procedure 
gets  called,  however,  the  canvas  package  does  some  processing.  If  the  event  is 
WIN_REPAINT  or  WIN_RESIZE,  the  canvas  package  calls  your  repaint  or 
resize  procedures  if  necessary.  If  the  event  is  SCROLL_REQUEST,  then  the  can¬ 
vas  package  performs  the  scrgU.^^  The  repaint,  resize  and  scroll  events  are  then 
passed  to  your  event  procedure.  In  the  case  of  events  which  have  x-y  coordi¬ 
nates,  the  canvas  package  translates  the  events  from  the  coordinate  space  of  the 
canvas  pixwin  to  that  of  the  logical  canvas. 

Translating  Events  from  Functions  are  provided  to  translate  event  coordinates  from  the  coordinate  space 

Canvas  to  Window  Space  of  the  canvas  to  the  coordinate  space  of  the  canvas  subwindow,  and  vice  versa. 

To  go  from  canvas  space  to  window  space,  use  canvas_window_event  ( ) . 
Keep  in  mind  that  the  can vas_window_e vent  function  changes  fields  in  its 
event  argument  structure.  For  example,  if  you  want  to  put  up  a  menu  in  a  canvas 

^  The  general  input  paradigm  for  Sunview  is  discussed  in  Chapter  6,  Handling  Input.  See  that  chapter  for  a 
full  discussion  of  the  available  input  evoits  and  how  to  use  them. 

Note  that  the  canvas  package  expeas  to  receive  these  events,  and  will  not  function  properly  if  you  disable 
them.  Also,  if  the  user  has  the  enabled  Lefi_Handed  option  in  the  Input  category  of  def  aultsedit(l), 
the  mouse  buttons  are  reversed:  MS_LEFT  refers  to  the  right  mouse  button,  MS_RIGHT  to  the  left  mouse 
button. 

If  you  want  write  a  procedure  which  is  called  before  the  repaint,  resize  or  scroll  event  is  processed  by  the 
canvas  package,  in  order  to  modify  the  interpretation  of  the  event,  you  must  interpose  on  the  event,  as  described 
in  Chapter  17,  The  Nolifier . 


Writing  Your  Own  Event 
Procedure 
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Border  Highlighting 


Example  4: 


subwindow,  you  need  to  specify  the  menu’s  location  in  the  coordinate  of  the 
subwindow,  not  of  the  canvas. 

To  go  from  window  space  to  canvas  space,  use  canvas_event  ( ) .  This 
returns  the  Event  *  it  is  passed,  with  the  x  and  y  fields  changed.  The  transla¬ 
tion  is  necessary  if  you  read  your  own  events  with  window_read_event  ( ) , 
described  in  the  next  chapter.  Handling  Input. 

The  SunView  eonvention  is  that  a  subwindow  indicates  that  it  is  accepting  key¬ 
board  events  by  highlighted  its  border.  By  default,  canvas  subwindows  do  not 
enable  any  keyboard  events,  so  the  border  is  not  highlighted.  However,  if  you 
explicitly  enable  keyboard  events,  by  consuming  WIN__ASCII_EVENTS,  the 
canvas  package  will  highlight  the  canvas  border  when  it  is  given  the  input  focus. 

The  program  below  prints  out  the  corresponding  string  when  the  user  types  0,1, 
or  2  into  its  canvas: 

' — — 

#include  <suntool/sunview.h> 
finclude  <suntool /canvas .h> 

static  void  my_event_proc { )  ; 

main{argc,  argv) 
int  argc; 
char  **argv; 

{ 

Frame  frame; 

frame  =  window_c reate (NULL,  FRAME,  0); 
window_create (frame,  CANVAS, 

WIN_CONSUME_KBD_EVENT,  WIN_ASCII_EVENTS , 
WIN_EVENT_PROC ,  my_e vent_pr oc , 

0); 

window_main_loop  (frame)  ; 
exit ( 0 ) ; 

} 

static  void 

my__event_proc  (canvas,  event) 

Canvas  canvas ; 

Event  *event ; 

{ 

char  *string  =  NULL; 

switch  (event_action (event) )  { 

case  ' 0'  : 

string  =  "zero”; 
break; 

case  ' 1'  : 

string  =  "one  "; 
break; 

s _ _ _ — - 
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case  '2'  : 

string  =  "two 
break; 


} 

if 


} 


default : 
break; 

(string  !=  NULL) 
pw_text (canvas_pixwin (canvas) , 
10,  10,  PIX_SRC,  NULL, 


string) ; 


5.8.  Color  in  Canvases  You  can  use  color  in  canvases  by  specifying  a  colormap  segment  for  the  canvas 

with  the  colormap  manipulation  routines  described  in  Chapter  6,  Handling  Input. 

Setting  the  Colormap  Segment  The  first  thing  to  note  is  that  since  the  canvas  pixwin  is  a  region  of  the 

WIN_PIXWIN,  you  must  also  set  the  colormap  segment  for  the  canvas  pixwin. 

Color  in  Retained  Canvases  If  the  canvas  is  retained,  then  the  colormap  segment  must  be  set  before 

CANVAS_RETAINED  is  set  to  TRUE.  This  is  because  the  canvas  package  wiU 
determine  the  depth  of  the  backing  pixrect  based  on  depth  of  the  colormap  seg¬ 
ment  defined  for  the  WIN_P  ixwiN.  (If  the  colormap  segment  depth  is  greater 
than  two,  then  the  full  depth  of  the  display  will  be  used.  Otherwise,  the  backing 
pixrect  depth  wUl  be  set  to  one.) 

Since  the  depth  of  the  backing  pixrect  is  determined  when  the  canvas  is  created, 
you  must  create  the  canvas  with  CANVAS_RETAINED  FALSE,  then  set  the 
colormap  segment,  then  set  CANVAS_RETAINED  to  true. 

Color  in  Scrollable  Canvases  If  the  canvas  has  scroUbars,  you  need  to  attach  the  scroUbars  to  the  canvas  after 

the  colormap  segment  has  been  changed.  If  the  canvas  has  already  been  created 
with  scrollbars  attached,  you  should  change  the  colormap,  then  re-attach  the 
scroUbars.  This  wiU  insure  that  the  scroUbar  pixwin  regions  use  the  new  color- 
map  segment. 
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Example  5: 


Below  is  an  example  of  setting  the  colormap  segment  for  a  canvas: 

- , 

♦include  <suntool/sunview.h> 

♦include  <suntool/canvas .h> 

♦include  <sunwindow/cms  rainbow. h> 


init_color_canvas (base^frame) 

Frame  base_frame; 

{ 

{ 

Canvas  canvas; 

Pixwin  *pw; 

unsigned  char  red[CMS_RAINBOWSIZE} ; 
unsigned  char  green [CMS_RAINBOWSIZE] ; 
unsigned  char  blue [CMS_RAINBOWSIZE] ; 

canvas  =  window_create (base_frame,  CANVAS, 

CANVAS_RETAI NED ,  FALSE , 

0); 

cms_rainbowsetup (red,  green,  blue); 

/*  set  the  WIN_PIXWIN  colormap  */ 

pw  =  (Pixwin  *)  window_get (canvas,  WIN_PIXWIN) ; 

pw_s  et  cms  name ( pw ,  CMS_RAI NBOW ) ; 

pw_j3Utcolormap  (pw,  0,  CMS_RAINBOWSIZE,  red,  green,  blue); 

/*  set  the  CANVAS_PIXWIN  colormap  */ 
pw  =  (Pixwin  *)  canvas_pixwin  (canvas) ; 
p w_set cms name (pw,  CMS_RAINBOW) ; 

pw_putcolormap (pw,  0,  CMS_RAINBOWSIZE,  red,  green,  blue); 

window_^set  (canvas, 

CANVAS_RETAINED,  TRUE, 

WIN_VERTICAL_SCROLLBAR,  scrollbar_create (0) , 
WIN_HORIZONTAL_SCROLLBAR,  scrollbar_create (0) , 

0); 

} 

} 

« - ____ - 
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Handling  Input 


Material  Covered 


Header  Files 


TTiis  chapter  explains  how  input  is  handled  in  SunView.  Specifically  it: 

□  gives  an  overview  on  how  input  is  handled  in  SunView 
a  describes  events  and  how  they  are  used; 

a  gives  various  classes  of  events  — Ascn,  action  events,  function  keys,  locator 

buttons,  locator  motion,  window  generated  events,  and  so  on; 

o  explains  the  input  focus  model  distinguishing  between  pick  and  keyboard 

focuses; 

n  shows  how  to  control  where  input  is  distributed  using  input  masks', 

□  shows  how  to  query  the  state  of  an  event; 

□  shows  how  to  explicitly  read  events. 

The  material  in  this  chapter  applies  to  the  window  system  as  a  whole.  However, 
it  is  of  special  interest  to  alerts  or  clients  of  canvases,  who  typically  wiU  want  to 
handle  events  themselves. 

The  definitions  necessary  to  use  SunView ’s  input  facilities  are  in  the  header  file 
<sunwindow/win_input .  h>,  which  is  included  by 
<sunwindow/window_hs .  h>,  which  in  turn  is  included  by  default  when 
you  include  <suntool/ sunview.h>. 


Related  Documentation 


Summary  Listing  and  Tables 


The  chapter  titled  Workstations  in  the  SunView  1  System  Programmer’s  Guide 
explains  the  input  system  at  a  lower  level,  covering  such  topics  as  how  to  add 
user  input  devices  to  SunView. 

To  give  you  a  feeling  for  what  you  can  do  with  events,  a  list  of  the  available 
event  descriptors  and  input  related  window  events  is  given  on  the  following  page. 
Many  of  these  are  discussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the 
Index  to  check).  All  are  briefly  described  with  their  arguments  in  the  input  sum¬ 
mary  tables  in  Qiapter  19,  SunView  Interface  Summary: 

□  the  Event  Descriptors  table  begins  on  page  333; 

n  the  Input-Related  Window  Attributes  table  begins  on  page  334. 
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Input-Related  Window  Attributes 

WIN_INPUT_DESIGNEE 

WIN_CONSUME_KBD_EVENTS 

WIN_GRAB_ALL_INPUT 

WIN_IGNORE_KBD_EVENTS 

WIN_KBD_FOCUS 

WIN_CONSUME_P ICK_EVENT 

WIN_KBD_INPUT_MASK 

WIN_I GNORE_P ICK_EVENT 

WIN  PICK  INPUT  MAS K 

WIN_CONSUME_P ICK_EVENTS 

WIN_CONSUME_KBD_EVENT 
WIN_I  GNORE_KBD_E  VENT 

WIN_IGNORE_P ICK_EVENTS 

Event  Descriptors 

WIN_NO_EVENTS 

WIN_RIGHT_KEYS 

WIN_ASCII_EVENTS 

WIN_TOP_KEYS 

WIN  IN  TRANSIT  EVENT S 

WIN  UP  ASCII  EVENTS 

WIN_LEFT_KEYS 

WIN_UP_E VENTS 

WIN__MOUS  E_BUTTONS 

Asun 
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6.1.  An  Overview  of  the 
Input  Environment 


How  are  events  generated  ? 


The  input  environment  for  SunView  differs  from  UNIX  programs.  Most  UNIX 
programs  read  characters  from  standard  input  by  using  either  the  read(2)  system 
call  or  the  standard  I/O  functions  such  as  getc(3S),  gets(3S),  or  scanf(3S). 
SunView  is  different  in  that  the  underlying  Notifier  formats  user  input  into  uni¬ 
form  events,  which  it  distributes  to  the  window’s  event  procedure. 

Figure  6-1  illustrates  how  events  are  generated  and  handled  in  SunView. 


Figure  6-1  Input  Events 
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What  does  the  Notifier  do  with 
these  events  ? 


How  do  windows  determine 
which  input  they  will  receive? 


6.2.  Events 


An  event  Procedure 


Events  are  generated  from  several  sources.  These  include  standard  devices  such 
as  the  keyboard  and  mouse,  special  input  devices  such  as  graphics  tablets,  and 
the  window  system  itself. 


SunView  does  not  directly  receive  events  from  the  hardware  devices.  Instead 
each  user  action  is  interpreted  by  a  “virtual”  user  input  device  (VUID)  interface. 
This  interface  packages  the  data  it  receives  into  an  event  and  sends  it  to  the  appli¬ 
cation  process.^^ 


The  Notifier  weaves  events  from  all  of  these  sources  into  a  single,  ordered  event 
stream.  This  event  stream  eliminates  the  need  for  the  application  to  poll  separate 
streams  from  the  different  devices. 

Because  the  underlying  Notifier  multiplexes  the  input  stream  between  windows, 
each  individual  window  operates  under  the  illusion  that  it  has  the  user’s  full 
attention.  That  is,  it  sees  precisely  those  input  events  that  the  user  has  directed  to 
it. 


Each  window  indicates  which  events  it  is  prepared  to  handle  using  input  masks, 
described  in  Section  6.6,  Controlling  Input  in  a  Window.  These  masks  only  let 
specified  events  through  to  the  process. 


As  discussed  in  the  previous  section,  each  user  action  generates  an  input  event. 
This  event  is  passed  to  your  event  procedure  as  an  Event  pointer  (type 
Event  *).  Three  types  of  information  are  encoded  as  part  of  an  event: 

□  an  identifying  code,  accessed  with  the  macro  e vent_act  ion  ( ) 

□  the  location  of  the  event  in  the  window’s  coordinate  system,  accessed  with 
the  macros  event_x  ( )  and  event_Y  ( ) 

n  a  timestamp,  accessed  with  the  macro  event_time  ( ) 


Notice  that  the  macro  event_action  ( )  has  replaced  the  old  event_id  ( ) . 
For  compatibility  reasons,  event_ici  ( )  is  still  supported,  so  that  old  code  that 
does  not  use  the  new  action  event  codes  will  still  work.  See  Section  6.4,  Classes 
of  Events,  for  an  explanation  of  action  events.  New  programs  that  want  to  take 
advantage  of  the  new  action  events  must  use  the  event_action  ( )  macro. 


Use  the  following  form  to  specify  an  an  event  procedure  in  your  applications: 
void 

sample_event_proc (window,  event,  arg) 

Window  window; 

Event  *event; 
caddr_t  arg; 


It  is  possible  to  bypass  the  VUID  and  receive  unencoded  events.  Refer  to  the  section  on  Unencoded  Input 
in  Chapter  7  of  the  SunView  1  System  Programmer's  Guide. 
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How  Subwindows  Handle 
Events 


6.3.  A  List  of  Events 


The  arguments  passed  in  are  the  window,  the  event,  and  an  optional  argument 
containing  data  pertaining  to  the  event.  For  example,  if  the  event  is  a 
SCROLL_REQUEST,  arg  will  be  the  scrollbar  that  sent  the  event. 

The  canvas  and  panel  subwindows  pass  events  that  they  receive  on  to  an  event 
procedure.  These  event  procedures  are  supplied  by  the  application  as  the  value 
of  wiN_EVENT_PROC.  If  you  set  the  wiN_EVENT_PROC  of  a  canvas  or  panel 
to  a  function  you  have  written,  you  can  receive  events  after  they  have  been  pro¬ 
cessed  by  the  canvas  or  panel.  Both  the  canvas  and  panel  packages  process 
SCROLL_REQUEST,  WIN_RESIZE,  and  WIN_REPAINT  events  before  calling 
your  event  procedure.  The  form  of  an  event  procedure  is: 

void 

sample_event_proc (window,  event,  arg) 

Window  window; 

Event  event ; 

caddr_t  arg; 

The  arguments  passed  in  are  the  window  (canvas  or  panel),  the  event,  and  an 
optional  argument  containing  data  pertaining  to  the  event.  For  example,  if  the 
event  is  a  SCROLL_request,  arg  wih  be  the  scrollbar  that  sent  the  event. 

The  default  panel  event  procedure  maps  events  to  actions  and  determines  which 
panel  item  to  send  the  event  to.  The  default  canvas  event  procedure  does  no 
further  processing  of  the  event.  You  can  call  the  default  window  event  procedure 
by  calling  window_de  fault  event_proc  ( >  with  the  same  arguments 
passed  to  your  event  procedure.^ 

Two  tables  are  given  on  the  following  pages.  Table  6-\,  Event  Codes,  lists  the 
predefined  event  codes  and  their  values.^^  The  event  id  or  code  numbers  that  the 
window  system  uses  to  represent  an  event  are  included  in  this  table.  These  event 
code  numbers  are  in  the  range  of  0-65535.  The  numbers  are  useful  when  debug¬ 
ging  a  program  because  the  debugger  reports  event  codes  as  decimal  integers  and 
not  as  names. 

Table  6-2,  Keyboard  Motions  and  Accelerators,  lists  the  event  name  and  its  asso¬ 
ciated  keyboard  accelerator. 


®  If  you  need  to  receive  an  event  before  it  is  processed  by  a  canvas,  panel,  or  any  other  type  of  window,  you 
can  use  the  more  general  notifier  interposition  mechanism  described  in  Chapter  17,  The  Notifier, 

^  The  same  table  also  t^pears  in  the  input  summary  section  of  Chapter  19,  SunView  Interface  Summary. 
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Table  6-1 

Event  Codes 

Event  Code 

Description 

Value  (for  debugging) 

ASCII_FIRST 

Marks  beginning  of  ASCII  range 

0 

ASCII_LAST 

Marks  end  of  ASCII  range 

127 

META_FIRST 

Marks  beginning  of  META  range 

128 

META_LAST 

Marks  end  of  META  range 

255 

ACTION  ERASE  CHAR  BACKWARD 

Erase  char  to  the  left  of  caret 

31744 

ACTION  ERASE  CHAR  FORWARD 

Erase  char  to  the  right  of  caret 

31745 

ACTION  ERASE  WORD  BACKWARD 

Erase  word  to  the  left  of  caret 

31746 

ACTION  ERASE  WORD  FORWARD 

Erase  word  to  the  right  of  caret 

31747 

ACT I ON  ERASE  LINE  BACKWARD 

Erase  to  the  beginning  of  the  line 

31748 

ACTION_ERASE_LINE_END 

Erase  to  the  end  of  the  line 

31749 

ACTION  GO  CHAR  BACKWARD 

Move  the  caret  one  character  to  the  left 

31752 

ACTION  GO  CHAR  FORWARD 

Move  the  caret  one  character  to  the  right 

31753 

ACTION  GO  WORD  BACKWARD 

Move  the  caret  one  word  to  the  left 

31754 

ACTION  GO  WORDEND 

Move  the  caret  to  the  end  of  the  word 

31756 

ACTION  GO  WORD  FORWARD 

Move  the  caret  one  word  to  the  right 

31755 

ACTION  GO  LINE  BACKWARD 

Move  the  caret  to  the  start  of  the  line 

31757 

ACTION  GO  LINE  END 

Move  the  caret  to  die  end  of  the  line 

31759 

ACTION  GO  LINE  FORWARD 

Move  the  caret  to  the  start  of  the  next  line 

31758 

ACTION_GO_COLDMN__BACKWARD 

Move  the  caret  up  one  line, 
maintaining  column  position 

31761 

ACTION_GO_COLUMN_FORWARD 

Move  the  caret  down  one  line, 
maintaining  column  position 

31762 

ACTION  GO  DOCUMENT  START 

Move  the  caret  to  the  beginning  of  the  text 

31763 

ACT I ON_GO_DOCUMENT_END 

Move  the  caret  to  the  end  of  the  text 

31764 

ACTION_STOP 

Stop  the  operation 

31767 

ACTION_AGAIN 

Repeat  previous  operation 

31768 

ACTION_PROPS 

Show  property  sheet  window 

31769 

ACTION_UNDO 

Undo  previous  operation 

31770 

ACTION_FRONT 

Bring  window  to  the  front  of  the  desktop 

31772 

ACTION_BACK 

Put  the  window  at  the  back  of  the  desktop 

31773 

ACTION_OPEN 

Open  a  window  from  its  icon  form  or  close 
if  already  open) 

31775 

ACTION_CLOSE 

Close  a  window  to  an  icon 

31776 

ACTION_COPY 

Copy  the  selection  to  the  clipboard 

31774 

ACTION_PASTE 

Copy  clipboard  contents  to  the  insertion  point 

31777 

ACTION_CUT 

Delete  the  selection,  put  on  clipboard 

31781 

ACTION  COPY  THEN  PASTE 

Copies  then  pastes  text 

31784 

ACTION_FIND_FORWARD 

Find  the  text  selection  to  the  right  of  the  caret 

31779 

ACTION  FIND  BACKWARD 

Find  the  text  selection  to  the  left  of  the  caret 

31778 

ACTION  FIND  AND  REPLACE 

Show  find  and  replace  window 

31780 

ACTION  SELECT  FIELD  FORWARD 

Select  the  next  delimited  field 

31783 

ACTION  SELECT  FIELD  BACKWARD 

Select  the  previous  delimited  field 

31782 
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Table  6-1 

Event  Codes —  Continued 

Event  Code 

Description 

Value  (for  debugging) 

ACTION_MATCH_DELIMITER 

Selects  text  up  to  a  matching  delimiter 

31894 

ACTION_QUOTE 

Causes  next  event  in  the  input  stream  to 
pass  imtranslated  by  the  keymapping  system 

31898 

ACTION_EMPTY 

Causes  the  subwindow  to  be  emptied 

31899 

ACTION_STORE 

Stores  the  specified  selection  as  a  new  file 

31785 

ACTION_LOAD 

Loads  the  specified  selection  as  a  new  file 

31786 

ACTION_GET_FILENAME 

Gets  the  selected  filename 

31788 

ACTION_SET_DIRECTORY 

Sets  the  directory  to  the  selection 

31788 

ACT I ON_INCLUDE_F I LE 

Selects  the  current  line  (in  pending-delete  mode) 
and  attempts  to  insert  the  file  described  by  that  selection 

31891 

ACTI ON_CAP  S_LOCK 

Toggle  caps  lock  state 

31895 

PANEL_EVENT_CANCEL 

The  panel  or  panel  item  is  no  longer  “current” 

32000 

PANEL_EVENT_MOVE_IN 

The  panel  or  panel  item  was  entered 

with  no  mouse  buttons  down 

32001 

PANEL__EVENT_DRAG_IN 

The  panel  or  panel  item  was  entared  with  one  or  more 
mouse  buttons  down 

32002 

SCROLL_REQUEST 

Scrolling  has  been  requested 

32256 

SCROLL_ENTER 

Locator  (mouse)  has  moved  into  the  scrollbar 

32257 

SCROLL_EXIT 

Locator  (mouse)  has  moved  out  of  the  scrollbar 

32258 

LOC_MOVE 

Locator  (mouse)  has  moved 

32512 

LOC_STILL 

Locator  (mouse)  has  been  still  for  1/5  second 

32513 

LOC_WINENTER 

Locator  (mouse)  has  entered  window 

32514 

LOC_WINEXIT 

Locator  (mouse)  has  exited  window 

32515 

LOC_DRAG 

Locator  (mouse)  has  moved  while  a  button  was  down 

32516 

LOC_RGNENTER 

Locator  (mouse)  has  entered  a  region  of  the  window 

32519  . 

LOC_RGNEXIT 

Locator  (mouse)  has  exited  a  region  of  the  window 

32520 

LOC_TRAJECTORY 

Inhibits  the  collapse  of  mouse  motions;  clients  receive 
LOC_TRAJECTORY  events  for  every  locator  motion 
the  window  system  detects. 

32523 

WIN_REPAINT 

Some  portion  of  window  requires  repainting 

32517 

WIN_RESIZE 

Window  has  been  resized 

32518 

WIN_STOP 

User  has  pressed  the  stop  key 

32522 

KBD_REQUEST 

Window  is  about  to  become  the  focus  of  keyboard  input 

32526 

KBD_USE 

Window  is  now  the  focus  of  keyboard  input 

32524 

KBD_DONE 

Window  is  no  longer  the  focus  of  keyboard  input 

32525 

SHIFT_LEFT 

Left  shift  key  changed  state 

32530 

SHIFT_RIGHT 

Right  shift  key  changed  state 

32531 

SHIFT_CTRL 

Control  key  changed  state 

32532 

SHIFT_META 

Meta  key  changed  state 

32534 

SHIFT_LOCK 

Shift  lock  key  changed  state 

32529 

SHIFT_CAPSLOCK 

Caps  lock  key  changed  state 

32528 
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Table  6-1 

Event  Codes —  Continued 

Event  Code 

Description 

Value  (for  debugging) 

BUT(i) 

Locator  (mouse)  buttons  1-10 

BUT(l)  is  32544 

MS_LEFT 

Left  mouse  button 

32544 

MS_MIDDLE 

Middle  mouse  button 

32545 

MS_RIGHT 

Right  mouse  button 

32546 

KEY_LEFT (i) 

Left  function  keys  1-15 

KEY_LEFT(1)  is  32554 

KEY_RIGHT (i) 

Right  function  keys  1-15 

KEY_RIGHT  ( 1 )  is  32570 

KEY_TOP{i) 

Top  function  keys  1-15 

KEY_TOP  (1)  is  32586 
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Table  6-2  Keyboard  Motions  and  Accelerators 

Command  Token 

SunView  4.0 

SunView  3.x 

ACTION  ERASE  CHAR  BACKWARD 

1  Delete  J 

( Delete  j 

ACTION  ERASE_CHAR_FORWARD 

rsivift-Delete ) 

( Shift-Delete  1 

ACTION  ERASE  WORD  BACKWARD 

(£ontrol-W  J 

1  qontrol-W  1 

ACTION  ERASE_WORD_FORWARD 

1  Shlft-ContTol-W  1 

( Shift-Control-W  1 

ACTION  ERASE  LINE  BACKWARD 

[  Control-U~l 

( Control-U  1 

ACT I ON_ERASE_L INE_END 

(  Shift-Control-U  1 

( Shift-Control-U  1 

ACTION  GO  CHAR  BACKWARD 

[  Control-B  J  or  (  Shift -Control-F  1  or 

imi 

ACTION  GO  CHAR  FORWARD 

[  Control-F  1  or  f  Shift-Control-B  1  or 

fRTD 

ACTION  GO  WORD  BACKWARD 

f  Control-comma )  or 

\  Shift-Control-Dgnod  i  or 
f  Shift-Control-s/<M)t  J 

ACTI ON_GO_WORD_END 

f  Control-oeriod ) 

ACTI ON_GO_WORD_FORWARD 

[  Control-s/aj)j )  or 
[  Shift-Control-co/?twbi  1 

ACTION_GO_LINE_FORWARD 

[ Control-semicolon  1  or f  Rll ) 

ACTION  GO  LINE  BACKWARD 

1  Control-A  )  or  1  Shift-C<xitrol-E  1 

ACTION  GO  LINE^END 

1  Control-E  J  or  [  Shift-Control-A  J 

ACTION  GO  COLUMN  BACKWARD 

[  Control-P )  or  ( Shift-Control-N  J  or 

ACTION  GO  COLUMN  FORWARD 

( Control-N  5  or  I  Shift-Ccaitrol-P  J  or 

(R18] 

ACTION  GO  DOCUMENT  START 

(  Shift-Control-Retum  1  or  [  R7  ) 

ACTION  GO  DOCUMENT  END 

I  Control-Return  !  or  1 R13  1 

1  Control-Return  1 

ACTION  STOP 

dD 

im 

ACTION  AGAIN 

[  L2 1  or  ( Meta-k ) 

rm 

ACTION  PROPS 

ClD 

fm 

ACTION  UNDO 

f  L4 1  or  1  Meta-C  1 

rm 

ACTION  FRONT 

ru) 

rm 

ACTION  BACK 

( Shift-L5  1 

1  Shift-L5  1 

ACTION  OPEN 

fm 

rm 

ACTION  CLOSE 

( Shifi-1.7 1 

( Shift-L7  I 

ACTION  COPY 

[  L6 1  or  ( Meta-C ) 

rm 

ACTION  PASTE 

ITDorlMcta-Vl 

( L8  1  or  (  Control-G  J 

ACTION  CUT 

lL10JorlA/«to-XJ 

1  LI 0 1  or  [  Control-D  J 

ACTION  COPY  THEN  PASTE 

(A/eta-Pl 

( Control-P  1 

ACT I ON_F I ND_FORWARD 

[  L9  ]  or  { Meta-V  1 

f  L9 1  or  [  Control-F  1 

ACT I ON_F I ND_BACKWARD 

I  Shift-L9  1  or  1  Shift-Meto-F  1 

I  Shift-L9  lor  ( Shift-CcHitrol-F  1 

ACTION  FIND_AND_REPLACE 

\  Control-L9  I 

ACT I ON_SELECT_FI ELD_FORWARD 

( Control 

ACT I ON_SELECT_FI ELD_BACKWARD 

1  Shift-Control-Tab  ] 

ACTION  MATCH  DELIMITER 

( Meta-H  1 

ACTION_QUOTE 

f  Me/fl-Q ) 

ACTION_EMPTY  (Document) 

r  Meta-E  1 

ACTION__STORE 

1  Meta-S  ] 
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Table  6-2 

Keyboard  Motions  and  Accelerators —  Continued 

Command  Token 

SunView  4,0 

SunView  3.x 

ACTION_LOAD 

1  MetaA,  | 

ACTION_INCLUDE_FILE 

1  Meta-1  ] 

ACTION_HELp3® 

1  Meta-1]  a  Meta-Shift-/ 1) 

ACT  I  ON_GE  T_F  I LENAME 

1  Escape ) 

[  Escape  1 

ACT  I  ON__CAP  S_LOCK 

GD 

ffn 

6.4.  Classes  of  Events 


ASCn  Events 


Locator  Button  Events 


Locator  Motion  Events 


This  section  groups  each  of  the  events  described  in  Table  6-1,  Event  Codes,  into 
logical  classes.  Each  class  is  described  below. 

The  event  codes  in  the  range  0  to  255  inclusive  are  assigned  to  the  ASCII  event 
class.  This  includes  the  standard  7-bit  ASCII  codes  and  their  8-bit  META  coun¬ 
terparts. 

If  a  user  strikes  a  key  which  has  an  obvious  ASCII  meaning;  that  is,  a  key  in  the 
main  typing  array  labeled  with  a  single  letter,  it  causes  the  VUID  to  enqueue  for 
the  appropriate  window  an  event  whose  code  is  the  corresponding  7-bit  ASCII 
character. 

The  META  event  code  values  (128  through  255)  are  generated  when  the  user 
strikes  a  key  that  would  generate  a  7-bit  ASCII  code  while  the  META  key  is  also 
depressed. 

The  standard  Sun  locator  is  a  three  button  mouse,  whose  buttons  generate  the 
event  codes  ms_left,  ms_middle  and  ms_right. 

In  general,  a  physical  locator  can  have  up  to  10  buttons  connected  to  it.  In  some 
cases,  the  locator  itself  may  not  have  any  buttons  on  it;  however,  it  may  have 
buttons  from  another  device  assigned  to  it.  A  light  pen  is  an  example  of  such  a 
locator. 

Each  button  that  is  associated  with  the  VUID’s  locator  is  assigned  an  event  code; 
the  i-th  button  is  assigned  the  code  BUT  ( i ) .  Thus  the  event  codes  ms_left, 
MS_MIDDLE  and  MS_RIGHT  correspond  to  BUT  ( 1 ) ,  but  ( 2 )  and  BUT  ( 3 ) . 

The  physical  locator  constantly  provides  an  (x,  y)  coordinate  position  in  pixels; 
this  position  is  transformed  by  SunView  to  the  coordinate  system  of  the  window 
receiving  an  event.  Locator  motion  event  codes  include  loc_move, 
LOC_DRAG,  LOC_TRAJECTORY,  and  LOC_STILL. 

Since  the  locator  tracking  mechanism  reports  the  current  position  at  a  set  sam¬ 
pling  rate,  40  times  per  second,  fast  motions  will  yield  non-adjacent  locations  in 
consecutive  events. 


^  If  your  keyboard  has  the  I L16 )  key,  you  may  also  use  it. 
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A  LOC  MOVE  event  is  reported  when  the  locator  moves,  regardless  of  the  state 
of  the  locator  buttons.  If  you  only  want  to  know  about  locator  motion  when  a 
button  is  down,  then  enable  L0C_DRAG  instead  of  LOC_MOVE.  This  will 
greatly  reduce  the  number  of  motion  events  that  your  application  has  to  process. 

When  you  enable  LOC_MOVE  or  LOC_DRAG,  the  window  system  gives  you  the 
current  locator  position  by  collapsing  consecutive  locator  motion  events  into  one. 
This  operation  is  appropriate  for  applications  such  as  dragging  an  image  from 
one  point  to  another,  in  which  it  is  important  to  keep  up  with  the  mouse  cursor. 

For  some  applications,  however,  each  point  on  the  cursor  trajectory  is  of  interest; 
for  example,  a  program  that  lets  the  user  draw.  In  these  situations  you  may  not 
want  to  collapse  consecutive  motion  events.  In  such  a  situation  you  should  ask 
for  LOC_TRA  JECTORY  events,  which  suppresses  any  event  collapsing  so  that 
you  get  all  the  locator  movements  that  the  window  system  sees. 

Note  that  when  you  ask  for  LOC_TRA JECTORY  events,  you  get  (many!) 
LOC_TRA JECTORY  events  in  place  of  LOC_MOVE’s,  but  you  still  get 
LOC_DRAG  events  if  you  have  enabled  them. 

If  you  ask  for  loc_STILL,  a  single  loc_STILL  event  will  be  reported  after 
the  locator  has  been  still  for  1/5  of  a  second. 


Window  events  are  generated  by  the  window  system  itself.  They  are  meaningful 
only  to  the  window  to  which  they  are  directed. 

To  be  informed  when  the  locator  enters  or  exits  a  window,  enable  events  with  the 
codes  LOC_WINENTER  and  L0C_WINEXIT. 

NOTE  If  you  are  using  the  tile  mechanism  described  in  the  SunView  1  System 

Programmer’s  Guide,  then  you  will  be  told  when  the  locator  has  entered  or 
exited  a  tile  using  the  loc_RGNENTER  and  loc_RGNEXIT  events.  To  receive 
these  events  you  must  also  have'LOC_MOVE  enabled. 

Resize  &  Repaint  Events  When  the  size  of  a  window  is  changed  (either  by  the  user  or  programmatically)  a 

WIN__RESIZE  event  is  generated  to  give  the  client  a  chance  to  adjust  any 
relevant  internal  state  to  the  new  window  size.  You  should  not  repaint  the  screen 
on  receiving  a  resize  event.  You  wiU  receive  a  separate  win_repaint  event 
when  a  portion  of  the  window  needs  to  be  repainted. 

NOTE  If  you  are  using  a  canvas  subwindow  you  will  not  need  to  track  resize  and 

repaint  events  directly.  The  canvas  package  receives  these  events,  computes  the 
new  window  dimensions  or  the  precise  area  requiring  repainting,  and  calls  your 
resize  or  repaint  procedures  directly.  See  Chapter  5,  Canvases  for  more  details. 


Window  Events 
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Keyboard  Focus  Events 


Stop  Event 


Function  Key  Events 


Three  events  let  your  application  interact  with  the  keyboard  focus  mechanism 
(the  keyboard  focus  is  explained  in  section  6.6,  Controlling  Input  in  a  Window ). 
When  the  user  explicitly  directs  the  keyboard  focus  towards  your  window,  you 
will  receive  a  KBD_REQUEST  event.  Your  window  will  then  become  the  key¬ 
board  focus  unless  you  call  window_refuse_kbd__f  ocus  ( ) .  Refusing  the 
keyboard  focus,  when  you  don’t  need  it,  contributes  to  the  usefulness  of  the  split 
keyboard/pick  focus  mode  available  as  a  runtime  option  to  sunview(l ). 

The  events  KBD_USE  and  KBD_DONE  parallel  the  locator  events 
LOC_WINENTER  and  LOC_WINEXIT,  respectively.  KBD_USE  indicates  that 
your  window  now  has  the  keyboard  focus  and  KBD_DONE  indicates  that  your 
window  no  longer  has  it. 

If  the  user  presses  and  releases  the  I  Stop  ]  key,  an  event  with  the  code 
WIN_ST0P  will  be  sent  to  the  window  under  the  cursor.^^  In  addition,  a 
SIGURG  signal  is  sent  to  the  window’s  process.  Your  application  can  use  the 
fStop  J  key  by  clearing  a  stop  flag  and  setting  a  S IGURG  interrupt  handler^^ 
before  entering  a  section  of  code  that  might,  from  the  user’s  perspective,  take  a 
long  time.  If  your  SIGURG  handler  is  called,  set  the  stop  flag  and  return.  In  the 
code  that  is  taking  a  long  time,  query  the  stop  flag  whenever  convenient.  When 
you  notice  that  the  stop  flag  has  been  set,  read  the  event,  then  gracefully  ter¬ 
minate  your  long  operation. 

The  function  keys  in  the  VUID  define  an  idealized  standard  layout  that  groups 
keys  by  location:  15  left,  15  right,  15  top  and  2  bottom.^^ 

The  event  codes  associated  with  the  function  keys  are  KEY_LEFT  ( i) , 
KEY_RIGHT  (i)  and  KEY_TOP  (i) ,  where  i  ranges  from  1  to  15. 

If  you  specifically  ask  for  a  function  key  event  code,  then  that  event  code  will  be 
passed  to  your  event  procedure. 

If  you  don’t  specifically  ask  for  a  given  function  key  event  code,  then  when  the 
user  presses  that  function  key  you  will  get  an  escape  sequence  instead  of  the 
function  key  event  code  (assuming  ASCII  events  have  been  enabled).  For  physi¬ 
cal  keystations  that  are  mapped  to  cursor  control  keys,  events  with  codes  that 
correspond  to  the  ANSI  X3.64  7-bit  ASCII  encoding  for  the  cursor  control  func¬ 
tion  are  transmitted.  For  physical  keystations  mapped  to  other  function  keys, 
events  with  codes  that  correspond  to  an  ANSI  X3.64  user-definable  escape 
sequence  are  transmitted. 


WIN_STOP  only  works  when  enabled  in  the  PICK  event  mask  and  not  in  the  KBD  event  mask. 

See  notify_set_signal_func  0  in  ia  Chapter  17,  The  Not ifier 

The  actual  position  of  the  function  keys  on  a  given  physical  keyboard  may  differ  —  see  kbd(5)  for  details 
on  various  keyboards. 
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Shift  Key  Events 


Semantic  Events 


Other  Events 


Applications  can  notice  when  a  shift  key  changes  state  by  enabling  events  with 
the  following  codes:  shift_left,  shift_right,  shift_ctrl, 
SHIFT_META,  SHlFT_LOCK  and  SHlFT_CAPSLOCK.  Although  these  codes 
allow  you  to  treat  one  or  more  shift  key  as  function-invoking  keys,  this  is  not 
recommended.  Instead  of  watching  for  the  event  directly,  you  should  query  the 
state  of  the  shift  keys  via  the  macros  described  on  the  next  page. 

Release  4.0  of  the  SunOS  introduces  a  new  type  of  event.  These  events  are 
called  action  events  and  represent  some  old  and  many  new  functions  in  the  win¬ 
dow  system.  They  are  similar  to  the  old  events  in  that  they  are  mapped  to 
specific  keys  on  the  keyboard.  That  is,  certain  combinations  of  keystrokes  in 
SunView  correspond  to  high-level  action  events.  For  example,  pressing  the 
[  Copy  I  key  copies' the  current  selection  to  the  Qipboard  in  text  subwindows, 
panels  and  tty  subwindows. 

Action  events  differ  from  the  old  events  in  that  applications  can  directly  express 
interest  in  the  high-level  action,  “Copy  the  selection  to  the  Qipboard”  rather  than 
in  the  low-level,  “The  L6  key  was  pushed”.  These  events  appear  in  Table  6-1 
with  the  prefix  ACTI0N_.  Applications  should  use  action  events,  because  left- 
handed  users  can  assign  1  Copy  1  to  a  different  key,  and  in  the  future  users  will  be 
allowed  to  tie  high-level  events  to  arbitrary  key  combinations. 

Your  application  may  receive  events  which  don’t  fall  into  any  of  the  classes 
described  above.  For  example,  a  non-standard  input  device,  such  as  a  second 
mouse,  may  emit  its  own  types  of  events.  Also,  a  software  object  may  communi¬ 
cate  with  other  software  objects  via  events,  as  is  the  case  when  a  scrollbar  sends  a 
SCROLL_REQUEST  to  a  panel  or  a  canvas. 

In  general,  your  event  procedure  should  not  treat  such  unexpected  events  as 
errors.  They  can  simply  be  ignored. 
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6.5.  Event  Descriptors  Events  have  been  further  grouped  into  descriptors.  Descriptors  describe  classes 

of  events  such  as  all  ASCII  events,  all  mouse  buttons,  aU  top  function  keys,  and 
so  on.  You  will  use  these  descriptors  to  set  input  masks,  described  in  Section  6.7 
Enabling  and  Disabling  Events 

The  descriptors  are  summarized  in  the  following  table. 

Table  6-3  Event  Descriptors 


Event  Descriptor 

Explanation 

WIN_NO_EVENTS 

Clears  input  mask  —  no  events  wiU  be  accepted.  Note:  the 
effect  is  the  same  whether  used  with  a  consume  or  an 

ignore  attribute.  A  new  window  has  a  cleared  input  mask. 

WIN_ASCI I_EVENT S 

All  ASCn  events.  ASCII  events  that  occur  while  the  META 
key  is  depressed  are  reported  with  codes  in  the  META  range. 

In  addition,  cursor  control  keys  and  function  keys  are 
reported  as  ANSI  escape  sequences:  a  sequence  of  events 
whose  codes  are  ASCII  characters,  beginning  with  <ESC>. 

WIN_IN__TRANSIT_EVENTS 
LOC_WINENTER,  and 

Enables  immediate  LOC_MOVE, 

LOC_WINEXIT  events.  Pick  mask  only.  Off  by  default 

WIN_LEFT_KEYS 

The  left  function  keys,  KEY_LEFT(1)  —  KEY_LEFT(15). 

WI  N_MOUSE_BOTTONS 

MS_MIDDLE 

and  MS_LEFT. 

Shorthand  for  MS__RIGHT, 

Also  sets  or  resets  WIN_UP_EVENTS. 

WIN_RIGHT_KEYS 

The  right  function  keys,  KEY_RIGHT(1)  —  KEY_RIGHT(15). 

WIN_TOP_KEYS 

The  top  function  keys,  KEY_TOP(l)  —  KEY_TOP(15). 

WIN_OP_ASCI  I_EVENTS 

Causes  the  matching  up  transitions  to  normal 

ASCn  events  to  be  reported  —  if  you  see  an  ’a’ 
go  down,  you’ll  eventually  see  the  matching  ’a’  up. 

WIN_UP_EVENTS 

Causes  up  transitions  to  be  reported  for  button 
and  function  key  events  being  consumed. 

6.6.  Controlling  Input  in  a  Input  may  be  controlled  using  input  focus  and  input  mask.  The  input  focus  is  the 

Window  window  that  is  currently  receiving  input.  The  input  mask  specifies  which  events 

a  window  will  receive  and  which  events  a  window  will  ignore.  This  section 
introduces  these  concepts  and  gives  the  algorithm  used  by  the  window  system  to 
decide  which  window  will  receive  a  given  input. 
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Input  Focus  SunView  supports  two  types  of  focus  models,  a  single  focus  model  and  a  split 

focus  model. 

The  single  focus  model  specifies  that  all  input,  no  matter  which  input  device  it 
came  from,  goes  to  the  same  window.  The  split  input  focus  lets  the  user  control 
the  pick  input  focus  and  the  keyboard  input  focus  separately. 

The  word  pick  comes  from  the  general  graphics  term  pick  device,  which  is  a  user 
input  device  that  allows  you  to  move  a  cursor  on  the  screen  and  then  click  a  but¬ 
ton  to  choose  a  point  on  the  screen.  The  most  common  pick  devices  are  the 
mouse,  light  pen  and  graphics  tablet. 

Under  the  split  input  focus  model,  mouse  clicks  and  keystrokes  may  be  distri¬ 
buted  to  different  windows.  This  makes  some  operations  easier  for  the  user.  For 
example,  the  user  can  select  text  in  one  window  and  move  it  to  another  window 
without  having  to  position  the  cursor  over  the  destination  window. 

In  general,  the  user  controls  the  keyboard  focus  by  using  specific  button  clicks 
and  controls  the  pick  focus  by  moving  the  mouse.  Sometimes,  it  is  appropriate 
for  input  focuses  to  be  under  program  control.  Generally  you  should  only  change 
an  input  focus  based  on  some  explicit  and  predictable  user  action. 

You  can  indicate  that  you  want  a  window  to  become  the  keyboard  focus  by  set¬ 
ting  the  wiN_KEYBOARD__FOCUS  attribute  to  true.  Note  that  this  is  only  a 
hint  to  the  window  system.  If  the  keyboard  focus  is  tied  to  the  pick  focus,  then 
this  call  has  no  effect.  The  target  window  might  also  refuse  the  keyboard  focus 
request  generated  by  this  call  (see  kbd_request  imder  Window  Events  above). 
You  can  set  the  pick  focus  via  the  wiN_MOUSE_XY  attribute,  which  sets  the 
mouse  cursor  to  a  particular  position  within  a  window. 

For  example,  the  call 

- — — - , 

window_set (win,  WIN_MOUSE_XY,  200,  300,  0); 

s _ _ _ ^ 

sets  the  cursor  to  the  window-relative  position  (200,  300)  and  sets  the  pick  focus 
to  win. 

Input  Mask  An  input  mask  specifies  which  events  a  window  will  receive  and  which  events  it 

will  ignore.  In  other  words,  an  input  mask  serves  as  a  read  enable  mask.  Each 
window  has  both  a  pick  input  mask,  to  specify  which  pick  related  events  it  wants, 
and  a  keyboard  input  mask,  to  specify  which  keyboard  related  events  it  wants. 

When  a  window  is  the  pick  focus,  its  pick  mask  is  used  to  screen  events.  When  a 
window  is  the  keyboard  focus,  its  keyboard  mask  is  used  to  screen  events. 


TTiis  section  describes  how  to  specify  which  events  a  window  will  receive  and 
which  it  will  ignore. 
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o 

Determining  which  Window  The  Notifier  determines  which  window  will  receive  a  given  event  according  to 
will  Receive  Input  the  following  algorithm: 

□  First,  the  keyboard  input  mask  for  the  window  which  is  the  keyboard  focus 
is  checked  to  see  if  it  wants  the  event.  If  so,  then  it  becomes  the  recipient; 
otherwise  the  next  test  is  applied. 

o  Second,  the  pick  input  mask  for  the  window  which  is  under  the  cursor  is 
checked  to  see  if  it  wants  the  event.  If  several  windows  are  layered  imder 
the  cursor,  then  the  event  is  tested  against  the  pick  input  mask  of  the  topmost 
window.  If  the  mask  wants  the  event,  then  it  becomes  the  recipient;  other¬ 
wise  the  next  test  is  applied. 

□  If  the  event  does  not  match  the  pick  input  mask  of  the  window  under  the  cur¬ 
sor,  then  the  event  will  be  offered  to  that  window’s  designee.  By  default  the 

is  the  window’s  owner.  You  can  set  the  designee  exphcitly  by  cal¬ 
ling  window__set  ( )  with  the  WIN_INPUT_DESIGNEE  attribute.^'^ 

□  If  an  event  is  offered  unsuccessfully  to  the  root  window,  it  is  discarded. 

Windows  which  are  not  in  the  chain  of  designated  recipients  never  have  a 
chance  to  accept  the  event. 

□  Occasionally  you  may  want  to  specify  that  a  given  window  is  to  receive  all 
events,  regardless  of  their  location  on  the  screen.  You  can  do  this  by  setting 
the  WIN_GRAB_ALL_INPUT  attribute  for  the  window  to  TRUE. 

o  If  a  recipient  is  found,  then  the  locator  coordinates  are  adjusted  to  the  coor-  C 

dinate  system  of  the  recipient,  and  the  event  is  appended  to  the  recipient’s 
input  stream.  Thus,  every  window  sees  a  single  ordered  stream  of  time- 
stamped  input  events,  which  contain  only  the  events  that  a  window  has 
declared  to  be  of  interest. 


^  Note  that  you  must  give  the  WIN_DE  VICE_NUMBER  of  the  window  you  wish  to  be  the  designee,  not  its 
handle.  This  is  to  allow  specifying  windows  in  another  user  process  as  the  input  designee.  So  the  following  call 
would  set  win2  to  be  the  designee  for  winl:  window_set  (winl,  WIN_INPUT_DESIGNEE, 
window_get (win2,  WIN_DEVICE_NUMBER) ) ; 
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6.7.  Enabling  and  You  specify  which  events  a  window  will  receive  and  which  it  will  ignore  by  set- 

Disabling  Events  ting  the  window’s  input  masks  via  the  following  set  of  attributes: 

Table  6-4  Attributes  Used  to  Set  Window  Input  Masks 


Events  Taking  a 

Single  Code 

Events  Taking  a  NuU 
Terminated  List 

WIN__CONSUME_KBD_EVENT 

WIN_CONSUME_KBD_EVENTS 

WI N_I GNORE_KBD_EVENT 

WIN_IGNORE_KBD_EVENTS 

WIN_CONSUME_P ICK_EVENT 

WIN_CONSUME_PICK_EVENTS 

WI N_I GNOREJP I CK_EVENT 

WIN_IGNORE_PICK_EVENTS 

The  above  attributes  take  as  values  either  event  codes  such  as  LOC_MOVE, 
MS_LEFT,  KEY_LEFT  ( 2 ) ,  and  SO  on,  or  event  descriptors.  The  attributes  in 
the  left  column,  ending  in  “_EVENT”,  take  a  single  code  or  descriptor,  while 
those  on  the  right,  ending  in  “_EVENTS”,  take  a  null  terminated  list 

Which  Mask  to  Use  To  enable  or  disable  ASCII  events,  use  the  keyboard  mask.  To  enable  or  disable 

locator  motion  and  button  events,  use  the  pick  mask. 

Function  keys  are  typically  associated  with  the  keyboard  mask,  but  sometimes  it 
makes  sense  to  include  some  function  keys  in  the  pick  mask  —  in  effect  extend¬ 
ing  the  number  of  buttons  associated  with  the  pick  device.  For  example,  in  the 
SunView  interface  the  ( Again  1. 1  Undo  1. 1  Copy ).  I  Paste  I.  [  Cut  1.  adid  [  Find  ]  func¬ 
tion  keys  are  associated  with  the  keyboard  mask,  while  the  I  Stop  1. 1  Front  1.  and, 

I  Open  1  keys  are  associated  with  the  pick  mask. 

Examples  The  event  attributes  cause  precisely  the  events  you  specify  to  be  enabled  or  dis¬ 

abled  —  the  input  mask  is  not  automatically  cleared  to  an  initial  state.  To  be 
sure  that  an  input  mask  will  let  through  the  events  you  specify,  first  clear  the 
mask  with  the  special  WlN_NO_EVENTS  descriptor.  Take,  for  example,  the  fol¬ 
lowing  two  calls: 

window_set (win,  WIN_CONSUME_PICK_EVENTS, 

WIN_MOUSE_BUTTONS ,  LOC_DRAG,  0, 

0)  ; 

window_set (win,  WIN_CONSUME_PICK_EVENTS, 

WIN_NO_EVENTS,  WIN_MOUSE_BUTTONS ,  LOC_DRAG,  0, 

0)  ; 

The  first  call  adds  the  mouse  buttons  and  LOC_DRAG  to  the  existing  pick  input 
mask,  while  the  second  call  sets  the  mask  to  let  only  the  mouse  buttons  and 
LOC_DRAG  through. 
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Canvases  by  default  enable  L0C_WINENTER,  L0C_winexit,  loc_move, 
and  the  three  mouse  buttons,  MS_LEFT,  MS__MIDDLE,  and  MS_RIGHT  ^5  You 
could  allow  the  user  to  type  in  text  to  a  canvas  by  calling: 

f  - ^ 

window_set (canvas,  WIN_CONSUME_KBD_EVENT ,  WIN_ASCII_EVENTS,  0) ; 
< _ > 


Sometime  later  you  could  disable  type-in  by  calling: 

f  N 

window_set (canvas,  WIN_IGNORE_KBD_EVENT,  WIN_ASCII_EVENTS,  0) ; 

^ 


An  application  needing  to  track  mouse  motion  with  the  button  down  would 
enable  LOC_DRAG  by  calling: 

- ^ - 

window_set (canvas,  WIN_CONSUME_PICK_EVENT,  LOC_DRAG,  0) ; 

s _ ^ 

You  can  enable  or  disable  the  left,  right  or  top  function  keys  as  a  group  via  the 
event  descriptors  WIN_LEFT_KEYS,  win_right_keys,  or 
WIN_TOP_KEYS.  Note  that  if  you  want  to  see  the  up  event  you  must  also  ask 
for  WIN_UP_EVENTS,  as  in: 

- - ^ 

window_set  (win,  WIN_CONSUME_KBD_EVENTS,  WIN_LEFT_KE YS , 

WI N_UP_EVENT  S ,  0 } ; 

>. _ > 

In  order  to  improve  interactive  performance,  in  the  default  case,  windows  do  not 
receive  locator  motion  events  (loc_winenter,  loc_winexit,  and 
LOC_MOVE)  until  after  a  L0C_STILL  has  been  generated.  If  each  window 
responds  to  all  of  the  events  that  are  generated  each  time  the  mouse  passes  over 
the  window,  then  the  response  time  of  the  system  will  be  slowed  down.  Each 
window  will  “wake  up”  when  the  mouse  passes  over  it  on  the  way  to  somewhere 
else  on  the  screen. 


If  you  want  a  window  to  receive  all  events,  even  if  the  mouse  is  just  passing  over 
the  window  without  stopping,  enable  win_in_transit_events,  with  a  call 
such  as: 


window  set (canvas,  WIN_CONSDME_PICK_EVENTS, 

- N 

WIN_IN_TRANSIT_EVENTS,  0); 

1 

_ / 

Note  that  the  canvas  package  expects  to  receive  these  events,  and  will  not  function  properly  if  you  disable 

them. 
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Setting  the  Input  Mask  as  a 
Whole 


Querying  the  Input  Mask 
State 


The  attributes  win_kbd_inpdt_mask  and  win_pick_input_mask  allow 
you  to  get  or  set  an  entire  input  mask.  Let’s  take  the  example  of  a  subroutine  that 
provides  interactive  feedback.  You  can  save  the  input  mask  on  entry  to  the  sub¬ 
routine,  set  up  the  mask  as  appropriate,  and  restore  the  original  mask  before 
returning  as  follows: 

- 

do_f  eedback { ) 

{ 

Input mask  *saved_mask; 

saved_mask  =  (Inputmask  *) 

window_get (win,  WIN_KBD_INPUT_MASK) ; 

window_set (win,  WIN_KBD_INPDT_MASK,  saved_mask,  0) ; 

} 

s _ / 


Keep  in  mind  that  the  inputmask  pointer  returned  by  window_get  ( )  points  to 
a  static  structure  which  is  shared  by  aU  windows  in  the  application.  Getting 
either  the  keyboard  or  pick  input  masks  for  another  window  will  cause  the  static 
structure  to  be  overwritten. 

You  can  use  window_get  ( )  with  wiN_CONSUME_PICK_EVENT  and 
WlN_CONSUME_KBD_EVENT  to  query  the  state  of  the  input  masks.  For  exam¬ 
ple,  the  following  call  will  find  out  whether  or  not  a  canvas  is  accepting 
LOC_DRAGs: 

- ; - ^ ^ 

flag  =  ( in t)window_get (canvas,  WIN_CONSOME_PICK_EVENT,  LOC_DRAG)  ; 


vsun 

Xr  microsystems 


Revision  A,  of  May  9,  1988 


96  SxmView  1  Programmer’s  Guide 


6.8.  Querying  and  Setting 
the  Event  State 


You  can  query  the  state  associated  with  an  event  using  the  following  macros,  all 
of  which  take  as  their  only  argument  a  pointer  to  an  Event. 


Table  6-5  Macros  to  Get  the  Event  State 


Macro 

Returns 

event  action  () 

The  identifying  code  of  die  event  The  codes  are  dis¬ 
cussed  in  the  previous  section.^® 

event  is  up{) 

TRUE  if  the  event  is  a  button  or  key 
event  and  the  state  is  up. 

event_is_down ( ) 

TRUE  if  the  event  is  a  button  or  key 
event  and  the  state  is  dowit 

event_x ( ) 

The  X  coordinate  of  the  locator  in  the  window’s 
coordinate  system  at  the  time  the  event  occurred. 

event_y ( > 

The  y  coordinate  of  the  locator  in  the  window’s 
coordinate  system  at  the  time  the  event  occurred. 

event  shiftmask() 

The  value  of  predefined  shift-keys 
(described  in  kbd(5)).  Possible  values; 

#define  CAPSMASK  0x0001 

#define  SHIFTMASK  0x00 OE 

♦define  CTRLMASK  0x0030 

♦define  META_SHIFT_MASK  0x0040 

event  time  () 

The  event’s  timestamp,  formatted  as  a  timeval 
struct,  as  defined  in  < sy s  /t ime .  h>. 

event  shift  is  down() 

TRUE  if  one  of  the  shift  keys  are  down. 

event  Ctrl  is  down ( ) 

TRUE  if  the  control  key  is  down. 

event  met a  is  down ( ) 

TRUE  if  the  meta  key  is  down. 

event_i s_button () 

TRUE  if  the  event  is  a  mouse  button. 

event_is_ascii () 

TRUE  if  the  event  is  in  the  ASCII  range  (0  thru  127). 

event_is_meta () 

TRUE  if  the  event  is  in  the  META  range  (128  thru  255). 

event  is  key  left  () 

TRUE  if  the  event  is  any  KEY_LEFT  ( i ) . 

event_is_key_right  () 

TRUE  if  the  event  is  any  KEY_RIGHT  (i ) . 

event_i s_key_top { ) 

TRUE  if  the  event  is  any  KEY_TOP  (i ) . 

In  addition  to  the  above  macros,  which  tell  about  the  state  of  a  particular  event, 
you  can  query  the  state  of  any  button  or  key  via  the  WIN_EVENT_STATE  attri¬ 
bute.  For  example,  to  find  out  whether  or  not  the  first  right  function  key  is  down 
you  would  call: 

kl_down  =  (int) 

window_get (canvas,  WIN_EVENT_STATE,  KEY_RIGHT  (1) ) ; 

. _ ^ 

The  call  will  return  non-zero  if  the  key  is  down,  and  zero  if  the  key  is  up. 

The  following  macros  are  provided  to  let  you  set  some  of  the  states  associated 
with  an  event. 


^  event_id()  is  repkcedby  event_action  ( )  However,  for  compatibility,  event_id  ( )  will  still 
be  supported. 
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Table  6-6  Macros  to  Set  the  Event  State 


Macro 

Effect 

event_set_action (event,  code) 

set  ei vent’s  id  to  code. 

event_set_shiftmask 

(event,  shiftmask) 

set  event’s  shiftmask  to  shiftmask. 

Possible  values: 

♦define  CAPSMASK 

0x0001 

♦define  SHIFTMASK 

OxOOOE 

♦define  CTRLMASK 

0x0030 

♦define  META_SHIFT_MASK 

0x0040 

event  set  x  (event,  x) 

set  event’s  x  coordinate  to  x. 

event_set_y (event,  y) 

set  event’s  y  coordinate  to  y. 

event_set_time (event ,  time) 

set  event’s  timestamp  to  time. 

event  set_up (event) 

set  state  of  a  button  event  to  up. 

event  set_down (event) 

set  state  of  a  button  event  to  down. 

6.9.  Releasing  the  Event  If  an  operation  generated  by  an  input  event  is  going  to  take  over  5  seconds,  then 

Lock  call  this  routine  to  allow  other  processes  to  get  input:^^ 

void 

window__release_event_lock  (window) 

Window  window; 

6.10.  Reading  Events  There  are  times  when  it  is  appropriate  to  go  get  the  next  event  yourself,  rather 

Explicitly  than  waiting  for  it  to  come  through  the  normal  event  stream  from  the  Notifier.  In 

particular,  when  tracking  the  mouse  with  an  image  which  requires  significant 
computation,  it  may  be  desirable  to  read  events  until  a  particular  action,  such  as  a 
mouse  button  up,  is  detected.  To  read  the  next  input  event  for  a  window,  bypass¬ 
ing  the  Notifier,  use  the  function: 

int 

window_read_event (window,  event) 

Window  window; 

Event  *event ; 

window_read_event  ( )  fiUs  in  the  event  structure,  and  returns  0  if  aU  went 
well.  In  case  of  error,  it  sets  the  global  variable  err  no  and  returns  -1. 

window__read_event  ( )  can  be  used  in  either  a  blocking  or  non-blocking 
mode,  depending  on  how  the  window  has  been  set  up.^^ 


For  more  details  see  the  section  on  synchrtmization  in  the  Workstations  chapter  of  the  SunView  1  System 
Programmer's  Guide. 

window_iead_eventO  is  the  high-level  library  standard  function  equivalent  of  input_readeventO  in  the 
low-level  library.  For  further  information,  see  Section  5.6,  Reading  Input  in  the  SunView  1  System 
Programmer’s  Guide. 
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Note  that  if  you  read  events  in  a  canvas  subwindow  yourself,  you  must  translate 
the  event’s  location  to  canvas  space  by  calling  canvas_event  ( ) : 

event_in_canvas_space  =  canvas_event (canvas,  event); 
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This  chapter  describes  the  pixwin  which  is  the  constmct  you  use  to  draw  or 
render  images  in  SunView.  The  most  basic  use  of  pixwins  is  to  draw  in  a  canvas 
subwindow. 

In  addition  to  basic  pixwin  usage,  this  chapter  covers: 

□  How  to  boost  your  rendering  speed  by  locking  and  batching 

□  How  to  use  regions  for  clipping 

□  How  to  manipulate  the  colbrmap 

□  How  to  use  the  plane  groups 

This  chapter  is  addressed  primly  to  programmers  who  write  simple  applica¬ 
tions  using  canvas  subwindows:  For  lower  level  details,  see  the  chapter  on 
Advanced  Imaging  in  the  SunView  System  Programmers  Guide. 

The  pixwin  drawing  operations  do  not  directly  support  high-level  graphics  opera¬ 
tions  such  as  shading,  segments,  3-D,  etc.  If  your  application  requires  these,  then 
you  should  consider  some  grapWcs  package  such  as  SunGKS,  SunCore,  or 
SunCGI.  AU  of  these  will  run  ib  windows  (see  the  SunCore  Reference  Manual 
and  SunCGI  Reference  Manual  for  more  information). 

The  definitions  necessary  to  use  pixwins  are  in  the  header  file 
<sunwindow/pixwin .  h>,  which  is  included  by 

<sunwindow/window_hs  .  h>,  which  in  turn  is  included  by  default  when 
you  include  <suntool/sunview.h>. 

To  give  you  a  feeling  for  what  you  can  do  with  pixwins,  the  following  page  con¬ 
tains  a  list  of  the  available  pixin  functions  and  macros.  Many  of  these  are  dis¬ 
cussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to  check).  All  are 
briefly  described  with  their  arguments  in  the  pixwin  summary  tables  in  Chapter 
19,  SunView  Interface  Summary: 

□  the  Pixwin  Drawing  Functions  and  Macros  table  begins  on  page  356; 

□  the  Pixwin  Color  Manipulation  Functions  table  begins  on  page  360. 
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Pixwin  Drawing  Functions  and  Macros 


pw_batch{pw,  n) 
pw_batch_off (pw) 
pw_batch_on (pw) 

pw_batchrop (pw,  dx,  dy,  op,  items,  n) 
pw_char (pw,  x,  y,  op,  font,  c) 
pw_close (pw) 

pw__copy (dpw,  dx,  dy,  dw,  dh,  op,  spw,  sx,  sy) 
pw_get (pw,  X,  y) 
pw_get_region_rect (pw,  r) 

pw_line (pw,  xO,  yO,  xl,  yl,  brush,  tex,  op) 
pw_lock  (pw,  r) 
pw_pf  sysclose  () 
pw_jpf  sysopen  { ) 

pw _polygon_2  (pw,  dx,  dy,  nbds,  npts,  vlist,  op,  spr,  sx,  sy) 
pw_polyline (pw,  dx,  dy,  npts,  ptlist,  mvlist,  brush,  tex,  op) 
pw_polypoint (pw,  dx,  dy,  npts,  ptlist,  op) 
pw_j>ut  (pw,  X,  y,  value) 

pw_read(pr,  dx,  dy,  dw,  dh,  op,  pw,  sx,  sy) 
pw_region (pw,  x,  y,  width,  height) 
pw_replrop (pw,  dx,  dy,  dw,  dh,  op,  pr,  sx,  sy) 
pw_reset (pw) 

pw_rop(pw,  dx,  dy,  dw,  dh,  op,  sp,  sx,  sy) 
pw_set_region_rect  (pw,  r,  use_same_pr) 
pw_show (pw) 

pw_stencil (dpw,  dx,  dy,  dw,  dh,  op,  stpr,  stx,  sty,  spr,  sx,  sy) 

pw_text (pw,  X,  y,  op,  font,  s) 

pw_traprop (pw,  dx,  dy,  t,  op,  pr,  sx,  sy) 

pw_ttext (pw,  X,  y,  op,  font,  s) 

pw_unlock (pw) 

pw_vector (pw,  xO,  yO,  xl,  yl,  op,  value) 
pw_write (pw,  dx,  dy,  dw,  dh,  op,  pr,  sx,  sy) 
pw_writebackground(pw,  dx,  dy,  dw,  dh,  op) 


Pixwin  Color  Manipulation  Functions 


pw_blackonwhite (pw,  min,  max) 
pw_cyclecolormap (pw,  cycles,  index,  count) 
pw_dbl_access (pw) 
pw_dbl_f lip (pw) 
pw_dbl_get (pw,  attribute) 
pw_dbl__re lease  ( ) 
pw_dbl_set (pw,  attributes) 
pw_getattributes (pw,  planes) 
pw_getcmsname (pw,  cmsname) 


pw_getcolormap (pw,  index,  count, 
red,  green,  blue) 
pw_getdefaultcms (cms,  map) 
pw__putattributes  (pw,  planes) 
pw_j3utcolormap  (pw,  index,  count, 
red,  green,  blue) 
pw_reversevideo (pw,  min,  max) 
pw_setcmsname (pw,  cmsname) 
pw  whiteonblack (pw,  min,  max) 
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7.1.  What  is  a  Pixwin? 


7.2.  Accessing  a  Pixwin ’s 
Pixels 


Obtaining  the  Window’s 
Pixwin 


An  image  in  SunView,  whether  on  the  screen  or  in  memory,  is  composed  of  dots 
called  pixels  and  is  represented  internally  as  a  rectangle  of  such  pixels.  The  pix- 
rect  structure  is  the  construct  used  at  a  low  level  to  access  an  image  and  operate 
on  it.  You  can  program  at  the  pixrect  level  to  draw  on  the  screen;  this  is  covered 
in  the  Pixrect  Reference  Manual. 

However,  in  SunView  drawing  operations  are  displayed  in  a  window  coexisting 
on  the  screen  with  other,  possibly  overlapping  windows.  Except  in  certain  cir¬ 
cumstances,  drawing  operations  should  be  “well-behaved,”  meaning  that  they 
should  not  spill  over  into  other  windows  and  they  should  not  be  visible  in  por¬ 
tions  of  the  window  which  are  covered  by  other  windows.  The  pixwin  is  the 
interface  through  which  you  operate  on  the  pixels  in  a  particular  window.  It 
guarantees  that  the  above  two  conditions  will  be  met. 

Each  pixel  has  a  value.  On  a  monochrome  display  the  value  is  1  or  0,  since  the 
pixel  can  only  be  on  or  off,  black  or  white.  Such  pixels  are  said  to  be  7  bit  deep. 
On  a  color  display  each  pixel  can  have  several  values  corresponding  to  different 
colors. 

This  section  summarizes  the  functions  provided  for  accessing  the  pixels  of  a 
pixwin.  Most  of  the  pw_*  functions  described  in  this  section  are  based  on 
corresponding  pr_*  routines,  which  are  fully  documented  in  the  Pixrect  Refer¬ 
ence  Manual.  For  full  discussion  of  the  semantics  of  a  given  pixwin  function, 
refer  to  the  discussion  of  the  corresponding  pixrect  function  in  the  Pixrect  Refer¬ 
ence  Manual  and/or  the  errata/addenda  section  of  the  most  recent  Release 
Manual. 

In  particular  the  pixrect  manual  gives  useful  values  for  the  op  argument  which  , 
determines  what  the  result  of  combining  the  source  and  destination  pixels  will 
be. 

The  procedures  described  in  this  section  will  maintain  the  memory  pixrect  for  a 
retained  pixwin.  That  is,  they  perform  their  operation  on  the  data  in  memory,  as 
weU  as  on  the  screen. 

All  of  these  procedures  require  the  pixwin  of  the  window  you  are  drawing  in  as 
an  argument.  To  draw  in  a  canvas,  you  use  the  pixwin  that  is  returned  by  the 
procedure: 

Pixwin  *pw; 

canvas__pixwin  (canvas) ; 

Canvas  canvas; 

Look  at  the  example  in  Section  5.1,  Creating  and  Drawing  into  a  Canvas,  to  see 
how  canvas_jpixwin  ( )  is  used. 

The  pixwin  is  also  available  as  the  value  of  the  CANVAS_PIXWIN  attribute  of 
the  canvas  subwindow.^^ 

39  Aside  from  the  canvas  pixwin,  all  windows,  regardless  of  type,  have  a  pixwin  which  is  available  as  the 
value  of  WIN  P IXWIN.  However,  most  applications  should  not  need  to  explicitly  write  pixels  into  (Xher  types 
of  windows. 
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Write  Routines 


Basic  RasterOp  Operations 


The  following  routines  allow  you  to  draw  areas,  backgrounds,  vectors,  text, 
polygons,  lines,  and  polylines  in  a  pixwin. 


The  following  are  the  basic  low-level  raster  operations  that  draw  on  the  screen. 
They  are  common  to  many  imaging  systems. 

pw_write (pw,  dx,  dy,  dw,  dh,  op,  pr,  sx,  sy) 

—  or — 

pw_rop (pw,  dx,  dy,  dw,  dh,  op,  pr,  sx,  sy) 

Pixwin  *pw; 

int  dx,  dy,  dw,  dh,  op,  sx,  sy; 

Pixrect  *pr; 


Other  Raster  Operations 


pw_wr  ite  ( )  and  pw_rop  ( )  are  different  names  for  the  same  procedure. 

They  perform  the  indicated  rasterop  (op)  from  the  source  pixrect  to  the  destina¬ 
tion  in  the  pixwin.  Pixels  are  written  to  the  rectangle  defined  by  dx,  dy,  dw,  and 
dh  in  the  pixwin  pw  using  rasterop  function  op.  dx  and  dy  are  the  position  of 
the  top  left-hand  comer  of  the  rectangle,  and  dw  and  dh  are  the  width  and  height 
of  the  rectangle.  They  are  copied  from  the  rectangle  with  its  origin  at  sx,  sy  in 
the  source  pixrect  pointed  to  by  pr. 


pw_wr  ite  ( )  is  essential  for  many  window  system  operations  such  as  scrolling 
a  window,  drawing  frames  and  borders,  and  drawing  an  icon  on  the  screen. 

The  routines  in  this  section  are  variations  on  the  basic  rasterop  routine. 

pw_writebackground (pw,  dx,  dy,  dw,  dh,  op) 

Pixwin  *pw; 

int  dx,  dy,  dw,  dh,  op; 


pw_wr  itebackground  { )  uses  a  conceptually  infinite  set  of  pixels,  all  of 
which  are  set  to  zero,  as  the  source.  It  is  often  used  to  clear  a  canvas  pixwin 
before  drawing  a  new  image.'^® 

The  following  routine  draws  a  pixel  of  value  at  ( x,  y )  in  the  addressed 
pixwin: 

pw_put  (pw,  X,  y,  value) 

Pixwin  *pw; 

int  X,  y,  value; 

Using  this  routine  to  draw  is  very  slow  and  should  be  avoided.  If  you  use  it,  be 
sure  to  read  the  later  sections  on  batching  and  locking. 


Canvases  will  automatically  clear  damaged  areas  if  they  are  set  not  to  be  retained,  or  if  the  attribute 
CANVAS_AUTO_CLEAR  is  set.  See  Chapter  5,  Canvases,  for  more  information. 
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There  is  a  similar  routine  to  draw  many  pixels  in  a  single  caU. 

pw_polypoint (pw,  dx,  dy,  npts,  ptlist,  op) 

Pixwin  *pw; 

int  dx,  dy,  npts; 

struct  pr_j30s  *ptlist; 
int  op; 

All  npt  s  points  in  the  array  pt  list  are  drawn  in  the  pixwin  pw  starting  at  the 
offset  dx,  dy  under  the  control  of  the  op  argument 

The  next  routine  draws  a  vector  of  pixel  value  from  (xO,  yO)  to  (xl,  yl)  in  the 
addressed  pixwin  using  rasterop  op: 

pw_vector (pw,  xO,  yO,  xl,  yl,  op,  value) 

Pixwin  *pw; 

int  xO,  yO,  xl,  yl,  op,  value; 

To  replicate  a  pattern  in  a  pixrect  onto  a  pixwin,  use: 

pw_replrop (pw,  dx,  dy,  dw,  dh,  op,  pr,  sx,  sy) 

Pixwin  *pw; 

int  dx,  dy,  dw,  dh,  op,  sx,  sy; 

Pixrect  *pr; 


pw_r  eplrop  ( )  replicates  a  small  “patch”  of  pattern  in  a  pixrect  onto  an  entire 
pixwin.  It  is  often  used  to  draw  a  patterned  background  in  a  window,  such  as  the 
root  gray  pattern  in  sunview(l).  Standard  patterns,  created  by  iconedit(l), 
may  be  found  in  /usr/ include/ image s/square_*  .pr. 


The  following  two  routines  write  a  string  of  characters  and  a  single  character, 
respectively,  to  a  pixwin,  using  rasterop  op  as  above: 

pw_text (pw,  X,  y,  op,  font,  s) 

Pixwin  *pw; 

int  X,  y,  op; 

Pixfont  *font; 
char  *s; 

pw_char(pw,  x,  y,  op,  font,  c) 

Pixwin  *pw; 

int  X,  y,  op; 

Pixfont  *font; 
char  c; 


n 
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Batching  and  Stenciling 
Routines 


These  text  rendering  routines  are  distinguished  by  their  own  coordinate  system: 
the  destination  is  given  as  the  left  edge  and  baseline  of  the  first  character.  The 
left  edge  does  not  take  into  account  any  kerning  (character  position  adjustment 
depending  on  its  neighbors),  so  it  is  possible  for  a  character  to  have  some  pixels 
to  the  left  of  the  x-coordinate.  The  baseline  is  the  y-coordinate  of  the  lowest 
pixel  of  characters  without  descenders,  ‘L’  or  ‘o’  for  example,  so  pixels  will  fre¬ 
quently  occur  both  above  and  below  the  baseline  in  a  string.'^l 


font  may  be  NULL  in  which  case  the  system  font  is  used. 

The  system  font  is  reference  counted  and  shared  between  software  packages. 
The  following  routines  are  provided  to  open  and  close  the  system  font:*^^ 

Pixfont  * 
pw_pf sysopen { ) 

pw_pfsysclose 0 


The  following  routine: 


pw_ttext (pw,  X,  y, 
Pixwin  *pw; 
int  X,  y, 

Pixfont  *font; 
char  *s; 


op. 


op; 


font,  s) 


is  just  like  pw_text  ( )  except  that  it  writes  transparent  text.  Transparent  text 
writes  the  shape  of  the  letters  without  disturbing  the  backgroimd  behind  it.  This 
is  most  useful  with  color  pixwins.  Monochrome  pixwins  can  use  pw_text  ( ) 
and  a  PIX_SRC  I  PIX_DST  op,  which  is  faster. 


Applications  such  as  displaying  text  perform  the  same  operation  on  a  number  of 
pixrects  in  a  fashion  that  is  amenable  to  global  optimization.  The  batchrop  pro¬ 
cedure  is  provided  for  these  situations: 


pw_batchrop (pw,  dx, 
Pixwin 
int 

struct  pr_prpos 


dy,  op,  items,  n) 
*pw; 

dx,  dy,  op,  n; 
items  [  ] ; 


Stencil  operations  are  like  raster  ops  except  that  the  source  pixrect  is  written 
through  a  stencil  pixrect  which  functions  as  a  pixel-by-pixel  write  enable  mask. 
The  indicated  raster  operation  is  applied  only  to  destination  pixels  where  the 
stencil  pixrect  stpr  is  non-zero;  other  destination  pixels  remain  unchanged. 


A  font  to  be  used  in  pw_text  ( )  is  required  to  have  the  same  pc_home .  y  and  character  height  for  all 
characters  in  the  font. 

The  system  font  can  also  be  obtained  by  calling  pf  default  () . 

The  structure  of  pr  prpos  is  given  in  Appendix  C  of  the  Pixrect  Reference  Manual. 
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Drawing  Polygons 


Drawing  Curved  Shapes 


Drawing  Lines 


pw_stencil (dpw,  dx,  dy,  dw,  dh,  op,  stpr,  stx, 
sty,  spr,  sx,  sy) 

Pixwin  *dpw; 

Pixrect  *stpr,  *spr; 

int  dx,  dy,  dw,  dh,  op,  stx,  sty,  sx,  sy; 


The  following  macro  draws  a  polygon  within  a  pixwin: 

pw_polygon_2 (pw,  dx,  dy,  nbds,  npts,  vlist,  op,  spr,  sx,  sy) 
Pixwin  *pw; 

int  dx,  dy,  nbds,  op,  sx,  sy; 

int  npt  s  [  ] ; 

struct  pr_j50S  *vlist; 

Pixrect  *spr; 


You  can  create  a  polygon  filled  with  a  solid  or  textured  pattern. 

pw_traprop  0  is  a  pixwin  operation  analogous  to  pw_rop  ( ) ,  which 
operates  on  a  trapezon  rather  than  a  rectangle: 

pw_traprop (pw,  dx,  dy,  t,  op,  pr,  sx,  sy) 

Pixwin  *pw; 

struct  pr_trap  t; 

Pixrect  *pr; 

int  dx,  dy,  op,  sx,  sy; 


pw_traprop  { >  writes  the  source  pixrect  pr  into  the  destination  pixwin  pw  via 
the  operation  op.  The  output  is  clipped  to  the  trapezon  t. 


The  following  routine  draws  a  solid  or  textured  line  between  two  points  with  a 
“brush”  of  a  specified  width: 

pw_line (pw,  xO,  yO,  xl,  yl,  brush,  tex,  op) 

Pixwin  *pw; 

int  xO,  yO,  xl,  yl,  op; 

struct  pr_brush  *brush; 
struct  pr_texture  *tex; 


There  is  a  similar  routine  to  draw  several  noncontiguous  line  segments  between  a 
set  of  points: 


pw  polyline (pw,  dx,  dy,  npts,  ptlist,  mvlist. 


Pixwin 

int 

struct  prjpos 
u_char 

struct  pr_brush 
struct  pr_texture 


*pw; 

dx,  dy,  npts,  op; 
*ptlist ; 

*mvlist ; 

*brush 

*tex; 


brush. 


tex. 


op) 


Asun 
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Read  and  Copy  Routines 


7.3.  Rendering  Speed 


The  following  routines  use  the  pixwin  as  a  source  of  pixels.  To  get  the  value  of 
the  pixel  at  ( x,  y  )  in  pixwin  pw  call: 


int 

pw_get (pw,  X,  y) 
Pixwin  *pw; 
int  X,  y; 


To  read  pixels  from  a  pixwin  into  a  pixrect  call: 


pw_read (pr, 
Pixwin 
int 

Pixrect 


dx,  dy,  dw,  dh,  op,  pw,  sx,  sy) 
*pw; 

dx,  dy,  dw,  dh,  op,  sx,  sy; 
*pr; 


This  routine  reads  pixels  from  pw  starting  at  offset  (  sx,  sy ),  using  rasteiop  op. 

The  pixels  are  stored  in  the  rectangle  with  its  origin  at  dx,  dy  of  width  dw  and 
height  dh  in  the  pixrect  pointed  to  by  pr. 

When  the  destination,  as  well  as  the  source,  is  a  pixwin,  use: 

pw_copy(dpw,  dx,  dy,  dw,  dh,  op,  spw,  sx,  sy) 

Pixwin  *dpw,  *spw; 

int  dx,  dy,  dw,  dh,  op,  sx,  sy; 

dpw  and  spw  must  be  the  same  pixwin.  Also,  only  horizontal  or  vertical  copies 
are  supported. 

'V  J 

These  read  and  copy  routines  fail  if  they  try  to  read  from  a  portion  of  a  non- 
retained  pixwin  which  is  hidden,  and  therefore  has  no  pixels.  Therefore  it  is  con¬ 
sidered  advanced  usage  to  caU  them  on  a  non-retained  pixwin;  refer  to  the  section 
entitled  Handling  Fixup  in  the  SunView  1  System  Programmer’s  Guide. 


Making  correct  and  judicious  use  of  explicit  display  locking  and/or  batching  is 
important  for  getting  the  best  display  speed  possible. 


There  are  two  major  impediments  to  you  getting  the  best  possible  display  render¬ 
ing  speed.  The  first  is  display  locking,  which  prevents  window  processes  from 
interfering  with  each  other  in  several  ways: 


n  Raster  hardware  may  require  several  operations  to  complete  a  change  to  the 
display;  one  process’  use  of  the  hardware  should  be  protected  from  interfer¬ 
ence  by  others  during  this  critical  interval. 

□  Changes  to  the  arrangement  of  windows  must  be  prevented  while  a  process 
is  painting,  lest  an  area  be  removed  from  a  window  as  it  is  being  painted. 

□  A  software  cursor  that  the  window  process  does  not  control  (the  kernel  is 
usually  responsible  for  the  cursor)  may  have  to  be  removed  so  that  it  does 
not  interfere  with  the  window’s  image. 


Display  locking  is  relatively  expensive  compared  to  the  time  it  takes  to  do  simple 
display  operations.  Thus  you  can  reduce  your  display  time  by  reducing  the 
number  of  times  that  you  have  to  acquire  the  display  lock.  The  subsection  below 
titled  Locking  explains  how  to  do  this. 


microsystems 


Revision  A,  of  May  9,  1988 


Chapter  7  —  Imaging  Facilities:  Pixwins  1 09 


Locking 


The  second  major  impediment  to  maximum  display  speed  is  the  use  of  retained 
pixwins.  It  is  obvious  that  if  you  have  to  write  to  tbe  screen  and  to  memory  for 
every  display  operation  that  it  wiU  take  longer  than  writing  to  only  one  place. 
Thus,  there  is  a  mechanism,  called  pixwin  batching  which  allows  you  to  write 
only  to  memory  and  then  refresh  the  screen  with  a  quick  raster  operation  from 
memory.  The  subsection  entitled  Batching  explains  how  to  use  batching. 

Locking  allows  a  client  program  to  obtain  exclusive  use  of  the  display.  If  the 
client  program  does  not  obtain  an  explicit  lock,  the  window  system  will.  For 
example,  if  your  application  is  going  to  draw  one  hundred  lines  it  can  either 
explicitly  lock  the  display  once,  draw  the  lines,  and  unlock  explicitly,  or  it  can 
ignore  locking  and  simply  draw  the  lines.  In  the  latter  case,  the  window  system 
will  perform  locking  and  unlocking  around  each  drawing  operation,  acquiring 
and  releasing  the  lock  one  hundred  times  instead  of  once. 

NOTE  For  efficiency’s  sake,  application  programs  should  lock  explicitly  around  a  body 
of  screen  access  operations. 

You  can  acquire  a  lock  by  calling  the  macro: 

pw_lock (pw,  r) 

Pixwin  *pw; 

Rect  *r; 

pw  is  the  pixwin  to  be  used  for  the  output;  r  is  the  rectangle  in  the  pixwin’s  coor¬ 
dinate  system  that  bounds  the  area  to  be  affected.  See  The  Rect  Structure  in 
Chapter  4,  Using  Windows,  for  an  explanation  of  the  Rect  structure. 
pw_lock  ( )  blocks  if  the  lock  is  unavailable  (if,  for  example,  another  process 
currently  has  the  display  locked). 

When  the  cursor  is  on  the  surface  where  drawing  occurs,  if  the  pixwin  is  locked 
with  pw_lo  ck  0  ,  sometimes  the  region  in  which  the  cursor  rect  resides  is  not 
drawn  to.  This  results  in  an  empty  region  (16x16  pixels)  when  the  cursor  is 
moved.  The  image  is  put  to  its  correct  state  when  it  is  redisplayed. 

Lock  operations  for  a  single  pixwin  may  be  nested;  inner  lock  operations  merely 
s;  increment  a  count  of  locks  outstanding  and  are  thus  very  lightweight.  Their 

affected  rectangles  must  lie  within  the  rectangles  affected  by  the  original  lock. 

To  decrement  the  lock  count,  call: 

pw_unlock (pw) 

Pixwin  *pw; 

When  the  lock  count  reaches  0,  the  lock  is  actually  released. 

Since  locks  may  be  nested,  it  is  possible  for  a  client  procedure  to  find  itself,  espe¬ 
cially  in  error  handling,  with  a  lock  which  may  require  an  indefinite  number  of 
unlocks.  To  handle  this  situation  cleanly,  another  routine  is  provided.  The  fol- 
.  ?  lowing  macro  sets  pw’s  lock  count  to  0  and  releases  its  lock: 

pw_reset (pw) 

Pixwin  *pw; 


A  su  n 
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Batching 


Acquisition  of  a  lock  has  the  following  effects: 

□  If  the  cursor  is  in  conflict  with  the  affected  rectangle,  it  is  removed  from  the 
screen.  While  the  screen  is  locked,  the  cursor  will  not  be  moved  in  such  a 
way  as  to  disrupt  any  screen  accessing. 

□  Access  to  the  display  is  restricted  to  the  process  acquiring  the  lock. 

□  Modification  of  the  database  that  describes  the  positions  of  all  the  windows 
on  the  screen  is  prevented. 

□  The  clipping  information  for  the  pixwin  is  validated  and,  if  necessary, 
updated. 

□  In  the  case  of  a  non-retained  pixwin  with  only  a  single  rectangle  visible,  the 
internals  of  the  pixwin  mechanism  can  be  set  up  to  bypass  the  pixwin 
software  by  going  directly  to  the  pixrect  level  on  subsequent  display  opera¬ 
tions. 

While  it  has  the  screen  locked,  a  process  should  nor. 

□  do  any  significant  computation  unrelated  to  displaying  its  image. 

□  invoke  any  system  calls,  including  other  I/O,  which  might  cause  it  to  block. 

□  invoke  any  pixwin  calls  except  pw_unlock  ( )  and  those  described  in  the 
previous  section.  Accessing  a  Pixwin' s  Pixels.  In  any  case,  the  lock  should 
not  be  held  longer  than  about  a  quarter  of  a  second,  even  following  aU  these 
guidelines. 

When  a  display  lock  is  held  for  more  than  two  seconds  of  process  virtual  time, 
the  lock  is  broken.  However,  the  offending  process  is  not  notified  by  signal, 
because  a  process  shouldn’t  be  aborted  for  this  infraction.  Instead,  a  message  is 
displayed  on  the  console. 

Batching  allows  you  to  write  only  to  the  memoiy  pixrect  of  a  retained  pixwin  and 
then  refresh  the  screen  with  the  memory  pixrect’ s  contents  at  specific  times.  If 
you  do  not  explicitly  batch  when  using  a  retained  pixwin,  the  window  system 
will  write  to  both  the  display  and  memory  on  every  display  operation. 

Considering  the  same  example  used  for  locking  above,  if  your  application  pro¬ 
gram  has  a  retained  pixwin  and  is  going  to  draw  one  hundred  lines,  it  can  either 
explicitly  start  a  batch,  draw  the  lines,  and  end  the  batch  explicitly,  or  it  can 
ignore  batching  and  simply  draw  the  lines.  In  the  latter  case,  the  window  system 
wiU  draw  the  lines  two  hundred  times  instead  of  one  hundred  times. 

NOTE  For  efficiency's  sake,  application  programs  should  batch  explicitly  around  a 
body  of  screen  access  operations  when  using  a  retained  pixwin. 


Asun 
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Two  macros  are  provided  to  control  batching: 

pw_batch_on (pw) 

Pixwin  *pw; 

pw_batch_of f (pw) 

Pixwin  *pw; 

pw_bat  ch_on  ( )  starts  a  batch;  pw_batch_of  f  ( )  refreshes  the  screen  with 
the  portion  of  the  memory  pixrect  that  has  changed.  While  batching,  the  pixwin 
internally  maintains  a  rectangle  that  describes  which  pixels  in  the  memory  pix¬ 
rect  need  to  be  transferred  to  the  screen  at  the  end  of  the  batch. 

NOTE  Don*  t  turn  batching  on  and  leave  it  on,  as  this  causes  problems  with  scrolling. 

The  recommended  use  is  batch_on  ( )  (draw  something  in  window) 
batch_off  0 . 

While  in  the  middle  of  batching,  your  code  might  reach  a  point  at  which  you 
would  like  the  screen  to  be  updated.  The  following  macro  refreshes  the  screen, 
but  otherwise  doesn’t  change  the  batching  mode: 

pw_show (pw) 

Pixwin  *pw; 


Unlike  locking  operations,  batch  operations  for  a  single  pixwin  do  not  nest. 
Thus,  each  batching  routine  in  this  section  affects  the  batching  mode/status. 

These  three  macros  —  pw_batch_on  ( ) ,  pw_batch_of  f  ( )  and 
pw_show  0  —  all  caU  the  routine  pw_bat  ch  ( )  which  actually  implements 
the  batching  mechanism.  You  can  call  pw_bat  ch  ( )  directly  to  teU  the  batch¬ 
ing  mechanism  to  refresh  the  screen  after  every  n  display  operations, 

pw_batch (pw,  kind) 

Pixwin  *pw; 

Pw_batch_type  kind; 

Because  the  routine  does  more  than  one  kind  of  thing,  calling  it  is  a  lithe  tricky, 
kind  is  the  kind  of  batching  requested.  You  use  the  following  macro  to  convert 
n,the  number  of  display  operations  you  want  to  be  batched  before  a  refresh,  to  a 
P  w_b  at  ch_t  yp  e : 

tdefine  PW_OP_COUNT (n)  ( (Pw_batch_type) (n) ) 

So,  to  have  batching  and  ensure  the  image  on-screen  is  refreshed  after  every  n 
operations,  caU: 

pw_batch (pw,  PW_OP_COUNT (n) ) ; 

Clients  with  a  group  of  screen  updates  to  do  can  gain  noticeably  by  doing  the 
group  as  a  batch.  Also,  the  locking  overhead,  discussed  above,  wiU  only  be 
incurred  when  the  screen  is  refreshed.  An  example  of  such  a  group  is  displaying 
a  screen  fuU  of  text,  or  a  series  of  vectors  with  pre-computed  endpoints. 

hi  considering  how  to  do  batching,  it’s  a  good  idea  to  be  sensitive  to  how  long 
the  user  is  staring  at  a  blank  screen  or  an  old  image,  and  adjust  the  rate  of  screen 
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Locking  and  Batching 
Interaction 


7.4.  Clipping  With  Regions 


refresh  accordingly. 

There  are  situations  in  which  batching  around  locking  calls  makes  sense.  Con¬ 
sider  that 

□  while  batching,  locking  calls  are  a  no-op; 

a  if  a  pixwin  is  not  retained,  batching  calls  are  a  no-op. 

Thus,  if  your  application  has  a  switch  to  run  retained  or  not,  it  makes  good  sense 
to  batch  around  locking  calls.  If  you  batch  around  locking  calls  then  your  appli¬ 
cation  gets  the  benefit  of  batching  if  running  retained  and  the  benefit  of  locking  if 
running  non-retained. 

Locking  around  batches,  on  the  other  hand,  is  not  very  efficient. 

You  can  use  pixwins  to  clip  rectangular  regions  within  a  window’s  own  rec¬ 
tangular  area.  The  region  operation  creates  a  new  pixwin  that  refers  to  an  area 
within  an  existing  pixwin: 

Pixwin  * 

pw_region (pw,  x,  y,  w,  h) 

Pixwin  *pw; 

int  X,  Y,  V,  h; 

pw  is  the  source  pixwin;  x,  y,  w  and  h  describe  the  rectangle  to  be  included  in 
the  new  pixwin.  The  upper  left  pixel  in  the  returned  pixwin  is  at  coordinates 
(0,0);  this  pixel  has  coordinates  ( x,  y)  in  the  source  pixwin. 

If  the  source  pixwin  is  retained,  the  new  region  will  be  retained  as  well.  How¬ 
ever,  the  region  refers  back  to  the  bits  of  memory  pixrect  of  the  source  pixwin 
when  accessing  the  image. 

To  change  the  size  of  an  existing  region,  caU: 

int 

pw_set_region_rect  (pw,  r,  use_saine_j3r) 

Pixwin  *pw; 

Rect  *r; 

unsigned  use_same__pr; 

The  position  and  size  of  the  region  pw  are  set  to  the  rect  *r;  a  return  value  of  -1 
indicates  failure.  This  is  more  efficient  then  destroying  the  old  region  and  creat¬ 
ing  a  new  one.  The  use_same_pr  flag  should  be  set  to  0  if  you  want  a  new 
retained  pixrect  allocated  for  the  region  that  is  the  size  of  the  region. 

To  determine  the  size  of  an  existing  region,  caU: 

int 

pw_get_region_rect  (pw,  r) 

Pixwin  *pw; 

Rect  *r; 
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7.5.  Color 


Introduction  to  Color 


The  Colormap 


*r  is  set  to  the  size  and  position  of  the  region  pw. 

When  finished  with  a  region,  you  should  release  it  by  calling:  to: 

pw_close  (pw) 

Pixwin  *pw; 

This  routine  frees  any  dynamic  storage  associated  with  the  pixwin,  including  its 
retained  memory  pixrect,  if  any.  If  the  pixwin  has  a  lock  on  the  screen,  it  is 
released. 

NOTE  You  should  close  any  regions  before  closing  the  pixwin  containing  the  regions. 

The  dicussion  which  follows  is  divided  into  three  sections: 

o  Introduction  to  Color,  which  introduces  the  concepts  of  the  colormap  and 
colormap  segments, 

□  Changing  the  Colormap,  which  describes  how  to  change  a  colormap  seg¬ 
ment,  and 

□  Using  Color,  which  describes  how  to  make  color  applications  compatible 
with  monochrome  and  grayscale  screens,  and  how  to  perform  smooth  anima¬ 
tion  by  using  double  buffering. 

Just  as  there  must  be  arbitration  between  different  windows  to  decide  what  is 
displayed  on  the  screen  when  several  windows  overlap,  there  must  likewise  be 
some  process  of  allocation  when  several  windows  want  to  display  different  sets 
of  many  colors  all  at  once.  To  understand  how  this  works  you  need  to  know  how 
color  is  handled. 

The  pixels  on  a  color  display  are  not  simply  on  or  off;  they  take  many  different 
values  for  different  colors.  On  all  current  Sun  color  displays'*^  each  pixel  has  8 
bits.  Such  an  “8  bit  deep”  pixel  can  have  any  value  from  0  to  255.  The  value  in 
each  pixel  helps  to  determine  what  color  appears  in  that  dot  on  the  screen,  but  it 
is  not  in  a  one-to-one  correspondence  with  the  color  displayed;  otherwise  Sun 
color  displays  would  only  be  able  to  display  256  different  colors. 

Instead,  the  value  of  the  pixel  serves  as  an  index  into  the  colormap  of  the  display. 
The  colormap  is  an  array  of  256  colormap  entries.  The  colormap  entry  for  each 
index  drives  the  color  that  is  actually  displayed  for  the  corresponding  pixel  value. 
A  colormap  entry  consists  of  8  bits  of  red  intensity,  8  bits  olgreen  intensity  and 
8  bits  of  blue,  packaged  into  the  following  structure: 

struct  singlecolor  { 

u_char  red,  green,  blue; 

}; 

Hence  a  Sun  color  display  is  capable  of  displaying  over  16  million  colors 
(because  each  colormap  entry  has  24  bits)  but  can  only  display  256  colors  simul¬ 
taneously  (because  there  are  only  256  colormap  entries). 


**  See  cgone(4S),  cgtwo(4S)  and  cgfour(4S)  in  the  UNIX  Interface  Overview  manual. 


microsystems 


Revision  A,  of  May  9, 1988 


! 


1 14  SunView  1  Programmer’s  Guide 


A  Colormap  Example 


Changing  the  Colormap 


Suppose  that  in  a  group  of  pixels  on  the  screen,  some  have  the  value  0  while  oth¬ 
ers  have  the  value  193.  All  pixels  with  the  same  value  will  be  displayed  in  the 
same  color.  The  colormap  determines  what  that  color  will  be.  If  entry  0  in  the 
colormap  of  the  screen  is 

red  =  250;  green  =  0;  blue  =3; 


then  the  pixels  with  a  value  of  0  will  come  out  bright  red.  If  entry  0  in  the  color- 
map  is  changed  to 

red  =1;  green  =8;  blue  =  2; 

then  the  pixels  with  a  value  of  0  will  immediately  change  color  to  an  almost- 
black  green.  Similarly,  entry  193  in  the  colormap  determines  what  color  the  pix¬ 
els  with  a  value  of  193  will  have. 


Because  changing  the  colormap  is  much  faster  than  redrawing  many  thousands  of 
pixels  with  a  new  value,  manipulating  the  colormap  is  the  basis  of  many  graphics 
and  animation  techniques.  For  examples  of  programs  that  manipulate  the  color- 
map,  run / usr/demo/suncube  or /nsr/demo/f light. 

Try  running  spheresedexno  -g  plus  another  color  program  at  the  same  time. 
You  wiU  notice  that  as  you  move  the  mouse  into  the  spheresdemo  window, 
the  colors  in  the  other  windows  on  the  display  change  dramatically.  This  is 
because  hardware  is  only  capable  of  displaying  256  colors  at  once.  When  two 
programs  that  each  want  to  display  256  different  colors  are  run  simultaneously, 
the  window  system  itself  must  manipulate  the  colormap.  When  the  cursor  enters 
one  of  the  windows,  the  window  system  changes  the  colormap  to  use  the  colors 
of  that  window. 


Colormap  Segments  The  window  system  allows  each  window  to  claim  a  portion  of  the  total  available 

colormap  entries,  called  a  colormap  segment.  The  colormap  segment  need  not  be 
the  same  in  aU  windows  of  a  tool:  frames  and  subwindows  can  have  different 
colormaps,  or  can  share  colormaps  (see  Sharing  Colormap  Segments  below).  If 
the  total  number  of  entries  in  all  the  colormap  segments  being  requested  exceeds 
the  limit  of  256  at  any  given  time,  the  window  system  gives  priority  to  the  win¬ 
dow  under  the  cursor,  and  removes  segments  belonging  to  other  windows  as 
necessary. 

The  window  system  loads  colormap  segments  at  arbitrary  locations  within  the 
colormap.  To  the  application  program,  this  indirection  is  transparent.  The  rou¬ 
tines  that  access  a  pixwin’s  pixels  do  not  distinguish  between  windows  which  use 
colormap  segments  and  those  which  use  the  entire  colormap. 

NOTE  While  you  can  have  multiple  pixwins  within  a  window,  there  is  only  one  color- 
map  segment  per  window.  A  separate  colormap  for  each  pixwin  in  a  window  is 
not  supported.  This  limitation  should  only  be  of  interest  if  you  are  using  pixwin 
regions  (described  in  the  SunView  System  Programmer’s  Guide). 
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Background  and  Foreground 


Default  Colonnap  Segment 


Changing  t^olors  from  the 
Command  Line 


Sharing  Colormap  Segments 


Every  colormap  segment  has  two  distinguished  values,  its  background  snA  fore¬ 
ground.  The  background  color  is  defined  as  the  value  at  the  first  position  of  a 
colormap  segment;  the  foreground  color  is  the  value  at  the  last  position. 

The  first  pixwin  created  for  a  window  sets  the  background  and  foreground  of  the 
window  to  be  those  of  the  default  colormap  segment.  This  is  the  monochrome 
colormap  segment  defined  in 

<sunwindow/cms_inono .  h>.  Subsequent  pixwins  created  for  the  window 
inherit  the  background  and  foreground  of  the  window. 

The  user  can  modify  the  default  colormap  for  aU  applications  by  invoking  - 
sunview  with  the  -F  and  -B  command  line  arguments.^^  The  user  can  also 
change  the  default  colonnap  segment  on  a  per-application  basis  by  invoking  the 
application  with  certain  flags.  The  -Wf  flag  sets  the  foreground  color,  -Wb  sets 
the  background  color,  and  -Wg  specifies  that  the  colormap  of  the  frame  will  be 
inherited  by  the  frame’s  sub  windows. 

The  equivalent  frame  attributes  for  these  flags  are 
FRAME_FOREGROUND_COLOR,  FRAME_BACKGROUND_COLOR,  and 
FRAME_INHERIT_COLORS. 

It  is  possible  for  different  processes  to  share  a  single  colormap  segment.  For 
some  applications,  you  want  to  guarantee  that  your  colormap  segment  is  not 
shared  by  another  process.  For  example,  a  colormap  segment  to  be  used  for  ani¬ 
mation,  as  described  later  in  the  section  on  Double  Buffering,  should  not  be 
shared.  The  way  to  ensure  that  a  colormap  segment  wiU  not  be  shared  by  another 
window  is  to  give  it  a  unique  name.  A  common  way  to  generate  a  unique  name 
is  to  append  the  process’  id  to  a  more  meaningful  string  that  describes  the  usage 
of  the  colormap  segment. 

If  a  colormap  segment’s  usage  is  static  in  nature,  then  it  pays  to  use  a  shared 
colormap  segment  definition,  since  colormap  entries  are  scarce.  Windows,  in  the 
same  or  different  processes,  can  share  the  same  colormap  by  referring  to  it  by  the 
same  name. 

There  are  three  basic  types  of  shared  colormap  segments: 

□  A  colormap  segment  used  by  a  single  program.  Sharing  occurs  when  multi¬ 
ple  instances  of  the  same  program  are  running.  An  example  of  such  a  pro¬ 
gram  is  a  color  terminal  emulator  in  which  the  terminal  has  a  fixed  selection 
of  colors. 

□  A  colormap  segment  used  by  a  group  of  highly  interrelated  programs.  Shar¬ 
ing  occurs  whenever  two  or  more  programs  of  this  group  are  running  at  the 
same  time.  An  example  of  such  a  group  is  a  series  of  CAD/CAM  programs 
in  which  it  is  common  to  have  multiple  programs  running  at  the  same  time. 


^  This  is  not  trae  for  a  Sun-3/1 10  and  other  machines  with  cgf  our  frame  buffers,  due  to  their  use  of  ai 
overlay  {dane  to  implement  most  monochrome  windows. 
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Example:  showcolor 


i 

I 


□  A  colomap  segment  used  by  a  group  of  unrelated  programs.  Sharing  occurs 

whenever  two  or  more  programs  of  this  group  are  running.  An  example  of 
such  a  colormap  segment  is  the  default  colormap,  cms_monochrome, 
defined  in  < sunwi ndo w/  cms_mono .  h>.  Other  common  useful  color- 
map  segment  definitions  that  you  can  use  and  share  with  other  windows 
include  cms_rgb . h,  cms_gray s . h,  cms_mono . h,  and 
cms_rainbow .  h,  found  in  <sunwindow/cms_* .  h>. 

The  program  on  the  following  page  shows  the  actual  colors  in  the  display’s 
colormap.  It  should  help  you  see  how  the  window  system  manages  the  color- 
map.  Run  this  program  soon  after  bringing  up  sunview,  then  run  several  color 
graphics  programs  such  as  the  demos  mentioned  earlier.  Try  bringing  up  dif¬ 
ferent  windows  with  different  foreground  and  background  colors,  as  in: 
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for  (i  =  0;  i  <  CMS_SIZE;  i++) 

recl[i]  =  green[i]  =  blue[i}  =  i; 
pw_setcmsname (pw,  "showcolor”) ; 

pw_putcolormap (pw,  0,  CMS_SIZE,  red,  green,  blue); 

/*  Draw  raitp  of  colors  */ 
for  (i  =  0;  i  <  CMS_SIZE;  i++) 

pw_rop(pw,  i*2,  0,  2,  CAN_HEIGHT, 

PIX_SRC  1  PIX_COLOR(i) ,  (Pixrect  *>0,  0,  0)  ; 
window_main_loop (frame) ; 
exit (0) ; 


Manipulating  the  Colormap 


The  following  sections  document  the  routines  that  implement  the  techniques 
described  above. 


To  change  a  window’s  colormap  segment,  you  must: 

1 .  Name  the  colormap  segment  with  pw_s et  cms name  ( ) . 

2.  Set  the  size  of  the  segment  by  loading  the  colors  with 
pw_putcolormap ( ) . 

It  is  important  that  these  two  steps  happen  in  order  and  together.  The  call  to 
pw_set  cms  name  ( )  does  not  take  effect  until  you  write  at  least  one  color 
value  into  the  colormap  with  pw_jput  colormap  ( ) . 

You  set  and  retrieve  the  name  of  a  colormap  segment  with  these  two  functions: 

pw_setcmsname (pw,  name) 

Pixwin  *pw; 

char  name [CMS_NAME SIZE] ; 

pw_getcmsname (pw,  name) 

Pixwin  *pw; 

char  name [CMS  NAMESIZE] ; 


If  you  set  the  foreground  and  badk- 
g round  colors  (which  are  entries 
count  - 1  and  0  in  the  colormap 
segment,  respectively)  to  the  same 
coior,  the  system  will  change  them 
to  the  foreground  and  background 
colors  of  sunview.  In  other  words, 
you  are  prevented  from  making  the 
foreground  and  background  colors 
of  a  pixwin  indistinguishable. 


Setting  the  name  resets  the  colormap  segment  to  a  NULL  entry.  After  calling 
pw_setcmsname  ( ) ,  you  must  immediately  call  pw_j)ut colormap  ( )  to  set 
the  size  of  the  colormap  segment  and  load  it  with  the  actual  colors  desired. 
pw_j)ut  colormap  ( )  and  the  corresponding  routine  to  retrieve  the  colormap’s 
state,  pw_getcolormap  { ) ,  are  defined  as  follows: 
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pw__putcolormap  (pw,  index, 
Pixwin  *pw; 

int  index, 

unsigned  char  red[]. 


count,  red,  green,  blue) 
count; 

green [ ] ,  blue [ ] / 


pw_getcolormap (pw,  index,  count,  red,  green,  blue) 
Pixwin  *pw; 

int  index,  count; 

unsigned  char  red[  ],  green [  ],  blue [  ]; 


pw_j5utcolormap  loads  the  count  elements  of  the  pixwin’s  colormap  seg¬ 
ment  starting  at  index  (zero  origin)  with  the  first  count  values  in  the  three 
arrays. 


The  first  time  pw_put  colormap  ( )  is  called  after  calling 
pw_setcmsname  ( ) ,  the  count  parameter  defines  the  size  of  the  colormap 
segment.  The  size  of  a  colormap  segment  must  be  a  power  of  2,  and  can’t  be 
changed  unless  pw_setcmsname  ( )  is  called  with  another  name.  You  can  call 
pwjput  colormap  ( )  subsequently  to  modify  a  subrange  of  the  colormap  — 
use  a  larger  value  for  index  and  a  smaller  value  for  count. 


NOTE  If  you  attempt  to  install  a  colormap  segment  that  is  not  a  power  of  2,  your  color- 
map  segment  has  a  high  likelyhood  of  taking  up  too  much  space.  This  means 
that  the  screen  will  flash  when  you  move  the  cursor  into  the  window  with  this 
odd  sized  colormap. 

In  Appendix  A,  Example  Programs,  there  is  a  program  called  coloredit  which 
uses  pw_put  colormap  ( }  to  change  the  colors  of  its  subwindows  as  the  user 
adjusts  sliders  for  red,  green  and  blue. 


Cycling  the  Colormap 


A  utility  is  provided  to  make  it  easy  to  cycle  colormap  entries: 


pw_cyclecolonnap (pw,  cycles,  index,  count) 
Pixwin  *pw; 

int  cycles,  index,  count; 


Miscellaneous  Utilities 


Starting  at  index,  the  count  entries  of  the  colormap  associated  with  the 
pixwin’s  window  are  rotated  among  themselves  for  cycles.  A  cycle  is  defined 
as  number  of  shifts  it  takes  one  entry  to  move  through  every  position  once. 

To  see  an  example  of  colormap  cycling,  run  jumpdemo  (6)  with  the  -c  option. 

If  you  are  are  going  to  cycle  one  of  the  common  colormap  segment  definitions, 
you  should  give  the  colormap  a  unique  name,  otherwise  Ae  colormap  of  other 
applications  wiU  change  as  well. 


The  following  utilities  are  provided  as  convenient  ways  to  set  file  forground  and 
background  colors  to  common  settings,  min  should  be  the  first  entry  in  the 
colormap  segment,  representing  the  background  color,  max  should  be  the  last 
entry,  representing  the  forground  color. 
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Using  Color 


Cursors  and  Menus 


pw_reversevideo (pw,  min,  max) 
Pixwin  *pw; 
int  min,  max; 


pw_blackonwhite (pw,  min,  max) 
Pixwin  *pw; 
int  min,  max; 


pw_whiteonblack (pw,  min,  max) 
Pixwin  *pw; 
int  min,  max; 


On  a  monochrome  display,  these  calls  don’t  take  effect  until  you  write  to  the 
pixwin.  On  a  color  display,  they  take  effect  immediately. 

This  section  gives  some  notes  on  the  use  of  color  by  cursors  and  menus,  how  to 
make  color  applications  compatible  with  monochrome  and  grayscale  screens,  and 
how  to  use  double  buffering  for  smooth  animation. 

Cursors  appear  in  the  foreground  color,  the  last  color  in  the  pixwin’ s  colormap. 

Menus  and  prompts  usq  fullscreen  access,  covered  in  Chapter  12,  Menus  and 
Prompts,  of  the  SunView  1  System  Programmer’s  Guide.  Fullscreen  access  saves 
the  colors  in  the  first  and  last  entries  of  the  screen’s  colormap,  puts  in  file  fore¬ 
ground  and  background  colors,  and  displays  the  menu  or  prompt.  This  means 
that  depending  on  where  your  application’s  colormap  segment  resides  in  the 
screen’s  colormap,  some  colors  in  your  tool  may  change  whenever  menus  or 
prompts  are  put  up.  You  can  allow  for  this  by  making  the  background  and  fore¬ 
ground  colors  in  your  colormap  segment  the  same  as  the  screen’s  background 
and  foreground. 

There  are  other  menu/cursor  “glitches”  that  occur  when  running  applications  on 
frame  buffers  which  support  multiple  plane  groups.  These  are  covered  in  the 
later  section  on  Multiple  Plane  Groups. 


Is  My  Application  Running  on  a  None  of  the  colormap  manipulations  described  in  this  chapter  causes  an  error  if 
Color  Display?  run  on  a  monochrome  display.  AU  colors  other  than  zero  map  to  the  foreground 

color,  so  if  your  application  displays  colored  objects  on  a  background  of  zero, 
they  wiU  appear  as  black  objects  on  a  white  foreground  on  a  monochrome 
display"^^.  The  window  system  detects  and  prevents  the  foreground  and  back¬ 
ground  being  the  same  color  on  color  displays. 

However,  you  may  may  want  to  determine  at  run  time  whether  your  application 
has  a  color  or  monochrome  display  available  to  it.  For  example,  when  displaying 
a  chart,  you  may  want  to  use  patterns  if  colors  are  not  available.  You  can  deter¬ 
mine  whether  the  display  is  color  or  monochrome  by  finding  out  how  deep  the 
pixels  are.  Each  pixwin  includes  a  pointer  to  a  pixrect  which  represents  its  pixels 
on  the  screen.  Pixrects,  in  turn,  have  a  depth  field  which  holds  the  number  of  bits 


^  Unless  you  are  running  with  black  and  white  inverted,  using  the  -i  option  to  sunview. 
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per  screen  pixel.  Thus 

I' 

Pixwin  *pw; 

I - > 

int  depth  =  pw->pw_pixrect->pr  depth; 

_ ^ 

will  have  a  value  of  1  for  windows  displayed  on  monochrome  devices,  and  a 
value  greater  than  1  for  color  screens.  Currently,  all  Sun  color  displays  have  8 
bits  per  pixel. 


There  is  no  way  to  tell  if  your  application  is  running  on  a  grayscale  monitor, 
since  it  runs  off  the  same  color  board.  The  grayscale  monitor  is  usually  driven 
from  the  red  output  of  the  color  board,  so  if  two  colors  have  different  green  and 
blue  values  but  the  same  red  value,  they  will  show  up  the  same  on  a  greyscale 
display. 

To  see  how  your  color  application  will  look  on  a  grayscale  monitor,  temporarily 
set  your  colormap  segment  so  that  the  green  and  blue  components  of  each  color- 
map  entry  are  the  same  as  the  red  component.  This  will  simulate  the  grayscale 
display  on  a  color  monitor. 

Software  Double  Buffering  Sometimes  you  want  to  rapidly  display  different  images  in  an  application.  If  you 

just  use  the  pixwin  write  operations  to  display  the  new  image,  the  redrawing  of 
the  pixels  will  be  perceptible  to  the  user,  even  though  the  operations  are  fast. 
Instead,  you  can  use  a  technique  called  software  double-buffering. 

As  we  have  seen,  on  a  color  display,  there  are  8  bits  associated  with  each  pixel. 

If  you  are  not  using  256  shades  at  once,  then  some  of  these  bits  are  unused. 

What  you  would  like  to  do  is  to  store  values  for  two  or  more  different  images  in 
these  8  bits,  but  only  display  one  set  of  values  at  a  time. 

The  first  goal  can  easily  be  accomplished  using  the  pw_put attributes  ( ) 
routine  to  restrict  writes  to  a  pr>rticular  set  of  planes: 

pw_j»utattributes  (pw,  planes) 

Pixwin  *pw; 
int  *planes; 


Simulating  Grayscale  on  a 
Color  Display 


planes  is  a  bitplane  access  enable  mask.  Only  those  bits  of  the  pixel 
corresponding  to  a  1  in  the  same  bit  position  of  *planes  will  be  affected  by 
pixwin  operations.  If  planes  is  NULL,  that  attribu^  value  will  not  be  written. 

A  corresponding  routine  is  provided  to  retrieve  the  value  of  the  access  enable 
mask: 

pw_getattributes (pw,  planes) 

P ixwin  *pw ; 
int  *planes; 

NOTE  Use  pw_put  attributes  ( )  with  care,  as  it  changes  the  internal  state  of  the 

pixwin.  The  correct  usage  is  to  first  save  the  existing  bitplane  mask  by  calling 
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pw_ge  tat  tributes  ( ) ,  then  caU  pw_putattributes  ( ) ,  then,  when 
done,  restore  the  initial  state  by  calling  pw_putattributes  ( )  with  the  saved 
mask. 

The  second  goal  —  only  displaying  what  is  in  some  of  the  planes  —  is  trickier. 
There  is  no  way  to  teU  the  hardware  to  only  look  at  the  values  in  some  of  the 
planes  to  determine  the  colors  to  show. 

What  you  do  instead  is  modify  the  colormap  so  that  only  values  in  certain  planes 
of  the  colormap  change  the  color  on  the  display,  so  in  effect  only  those  planes  are 
visible.  For  example,  to  display  two  different  four-color  images  you  could  use 
the  colormap  shown  in  the  following  table. 

Table  7-1  Sample  Colormap  to  Isolate  Planes 


Pixel  Value 

Colormap  A 
(Only  upper  planes 
are  “visible'") 

Colormap  B 
(Only  lower  planes 
are  "visible" 

0  0  0  0 

blue 

blue 

0  0  0  1 

blue 

red 

0  0  10 

blue 

green 

0  0  11 

blue 

pink 

0  10  0 

red 

blue 

0  10  1 

red 

red 

0  110 

red 

green 

0  111 

red 

pink 

10  0  0 

green 

blue 

10  0  1 

green 

red 

10  10 

green 

green 

10  11 

green 

pink 

110  0 

pink 

blue 

110  1 

pink 

red 

1110 

pink 

green 

1111 

pink 

pink 

From  the  above  table,  you  can  see  that  if  colormap  A  is  set  (using 
pw_put  colormap  ( )  ),  then  no  matter  what  the  value  in  the  two  lower  planes, 
the  color  displayed  is  the  same;  the  value  in  the  upper  two  planes  alone  controls 
the  color.  So,  if  you  use  this  colormap  while  only  enabling  the  two  lower  planes 
(by  passing  pw_j3ut attributes  ( )  the  value  3  ),  then  the  values  you  write 
into  the  lower  planes  won’t  change  what  is  shown. 

When  you  switch  to  colormap  B,  the  situation  is  reversed.  Only  the  values  in  the 
lower  planes  affect  what  is  visible.  You  would  then  pass 
pw_j3utattr  ibutes  ( )  the  value  12  to  write  to  the  upper  two  planes.  The 
two  sets  of  colors  need  not  be  the  same,  so  you  can  switch  between  two 
different-colored  images. 
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Using  Software  Double 
Buffering  For  Smooth 
Animation 


Hardware  Double-Buffering 


You  would  use  the  same  technique  to  switch  between  more  images  and/or  to 
display  more  colors.  You  can  display  two  different  images,  each  with  16  dif¬ 
ferent  colors,  or  8  different  monochrome  images,  or  values  in  between. 

One  application  of  the  above  technique  is  to  provide  smooth  animation.  To 
move  an  image  across  the  screen,  you  must  draw  it  in  one  location,  erase  it,  and 
redraw  it  in  another.  Even  on  a  fast  system,  the  erasing  and  redrawing  is  visible. 
You’d  like  the  object  to  immediately  appear  in  its  new  position,  without  disap¬ 
pearing  momentarily.  You  can  do  this  by  alternating  two  colormaps  so  that  the 
object  disappears  in  its  old  location  and  reappears  in  a  new  one.  ITiis  is  called 
software  double-buffering,  because  you  are  using  the  display  planes  as  alternat¬ 
ing  buffers;  as  you  write  to  one  set  of  planes,  the  other  set  of  planes  is  displayed. 

The  colormaps  in  the  table  on  the  preceding  page  come  from  the  software  pro¬ 
gram  animatecolor  in  Appendix  A,  Example  Programs.  This  program  uses 
software  double  buffering  to  animate  some  squares.  The  routines  it  uses  to  create 
the  two  colormaps  and  swap  between  them  are  complicated,  but  can  be  reused  in 
more  sophisticated  graphics  applications. 

The  following  routines  will  allow  programs  to  do  true  hardware  double-buffering 
on  the  ThecgSboard.  on  the  device  driver  interface,  refer  the  the  cgtwo(4S) 
manual  page.  color  framebuffer  and  on  future  framebuffers  that  support 
double-buffering. 

Double-buffering  is  treated  as  an  even  scarcer  resource  than  colormaps,  since 
only  one  window  can  be  truly  double-buffered  at  any  one  time.  The  cursor  con¬ 
trols  which  window  will  flip  the  display  buffers.  Applications  are  able  to  run  the 
same  code  on  non-double-buffered  displays  and  it  will  be  as  if  the  double- 
buffering  calls  were  never  made.  The  following  code  fragment  contains  proto¬ 
typical  application  code. 


Rect  rectangle; 

Pixwin  *pw; 
rectangle . r_lef t=  . . . ; 

if  (!pw_dbl_get  (pw,  PW_DBL_AVAIL) ) 
{  ...  if  program  cares ...  } 
pw_cibl_access  (pw)  ;  ^ 

while  (rendering_frames)  { 

...  calculate  one  frame  ... 
pw_lock  (pw,  Srectangle) ; 

...  render  one  frame ... 

...  may  include  unlocks  and  locks ... 
pw_cibl_flip  (pw)  ; 
pw_unlock  (pw) ; 

} 

pw_dbl_release  (pw)  ; 


The  cg5  board  is  binary  compilable  with  both  the  Sun-3  Color  Board  and  the  Sun-2  Color  Board.  cg5  is 
necessary  for  hardware  double-buffering. 


wsun 

Xr  microsystems 


Revision  A,  of  May  9, 1988 


Chapter  7  —  Imaging  Facilities:  Pixwins  123 


The  notion  of  the  “active”  double-buffering  window  is  important.  There  is  at 
most  one  active  window  at  a  time.  If  the  cursor  is  in  a  double-buffering  window, 
then  the  window  is  the  active  double-buffering  window.  If  the  cursor  leaves  the 
active  window,  that  window  remains  active  until  the  cursor  enters  another 
double-buffering  window.  If  the  active  double-buffering  window  dies,  goes 
iconic,  or  becomes  totally  obscured,  and  the  cursor  is  not  left  in  a  double¬ 
buffering  window,  then  the  top-most  visible  double-buffering  window  becomes 
the  active  window  (if  there  is  one). 

Only  the  active  window  wiU  be  allowed  to  write  to  a  single  buffer.  All  other  win¬ 
dows  write  to  both  buffers,  so  that  when  the  display  flips  to  the  other  buffer,  their 
contents  remain  unchanged.  The  notion  of  active  will  change  only  during  a 
pw_dbl_f  lip  ( )  call. 

pw_cibl_accessO  which  resets  the  window’s  data  structure  so  that  first  frame 
win  be  rendered  to  the  background.  The  very  first  double  buffer  sets  both  READ 
and  WRITE  to  the  backgound.  pw_dbl_acces  s()  should  only  be  called  when 
ready  to  actively  animate: 

pw_dbl_access  (pw) 

Pixwin  *pw; 

If  the  pixwin’s  window  has  not  been  accessed  for  double-buffering  then  there  is 
no  change,  and  both  buffers  will  be  written  to. 

If  the  window  is  marked  as  accessible  for  double-buffering  and  the  window  is 
“active” ,  then  the  frame  double-buffering  control  to  whatever  this  window 
requested  with  its  last  pw_dbl_set  ( )  call.  If  there  was  no  pw_dbl_set  ( ) 
caU,  then  set  WRITE  and  READ  to  the  background.  Change  the  frame  buffer 
double-buffering  control  bits  to  reflect  this. 

If  the  window  is  accessible  for  double-buffering  then  potentially  flip  the  display. 
The  display  is  flipped  only  if  the  window  is  “active”  :  pw_dbl_f  lip  { )  deter¬ 
mines  if  its  window  has  become  active: 

pw__dbl_f  lip  (pw) 

Pixwin  *pw; 


The  flip  can  be  done  inside  or  outside  of  a  lock  region  although  it  may  be  prefer¬ 
able  to  place  inside  a  lock  region  just  before  an  unlock  so  that  calculations  for  the 
next  frame  can  proceed  even  if  another  window  momentarily  grabs  the  lock.  The 
flip  from  one  buffer  to  another  is  synchronized  with  the  display’s  vertical  retrace. 

The  procedure 

pw_dbl_release  (pw) 

Pixwin  *pw; 

signifies  the  end  of  double-buffering  by  the  window  associated  with  the  pixwin. 
CaU  pw_dbl_release  ( )  as  soon  as  your  program  has  completed  a  section  of 
active  animation.  This  procedure  wUl  copy  the  foreground  buffer  to  the  back¬ 
ground.  Because  of  this,  it  is  important  to  leave  the  animation  loop  after  a 
pw_dbl_f  lip  ( )  has  been  done  and  before  drawing  the  next  frame  has  started. 
Otherwise,  the  window  wiU  contain  an  incomplete  buffer  image  after  the  release. 
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SimView  provides  the  ability  for  an  actively  double-buffering  window  to  write  to 
both  buffers.  For  example,  the  instrument  gauge  readings  can  be  set  in  a  real¬ 
time  simulator.  If  pw  is  not  the  active  double  buffer,  the  frame  buffer  control  bits 
are  not  changed.  The  procedure  and  the  attributes  that  it  may  use  are  discussed 
below. 

pw_cibl_set  (pw,  attributes) 

Pixwin  *pw; 

<attribute-list>  attributes; 


Table  7-2  Pixwin-Level  set  Attributes 


Attribute _ Possible  Values  to  set _ 

PW_DBL_WRITE  PW_DBL_FORE,  PW_DBL__BACK,  PW_DBL_BOTH 

PWDBLREAD  PW_DBL  FORE,  PW  DBL  BACK 


The  attribute  value  returned  from  pw_dbl_get  ( )  does  not  reflect  the  true  state 
of  double  buffering  hardware.  This  is  especially  true  if  the  active  double  buffer 
is  not  this  pixwin.  The  procedure  and  the  attributes  that  is  uses  are  given  below. 

pw_dbl_get (pw,  attribute) 

Pixwin  *pw; 

Pw_dbl_attribute  attribute; 


Table  7-3 


Pixwin-Level  get  Attributes 


Attribute 

Possible  Values  Returned 

PW_DBL_AVAIL 

PW  DBL  DISPLAY 

PW_DBL_EXISTS 

PW  DBL  WRITE 

PW  DBL  FORE,  PW  DBL  BACK,  PW  DBL  BOTH 

PW_DBL_READ 

PW_DBL_FORE ,  PW_DBL_BACK 

7.6,  Plane  Groups  and  the  The  Sun-3/1 10,  Sun-3/60,  and  Sun-4/1 10  color  machines  use  the 

eg  four  Frame  Buffer  cgf  our  ( 4  s )  ^^  frame  buffer,  which  supports  multiple  “plane  groups.”  Each 

displays  either  24-bit  color  or  black  and  white.  In  the  former  case  its  color  is 
determined  by  a  value  in  an  8-bit  color  buffer,  in  the  latter  case,  a  monochrome 
buffer  called  the  overlay  plane. 

Whether  the  pixel  displays  in  color  or  blacl^white  is  controlled  by  the  value  for 
the  pixel  in  the  enable  plane,  a  third  plane.  If  the  value  in  the  enable  plane  is  not 
set,  then  the  8-bit  deep  value  in  the  color  buffer  is  passed  to  the  circuitry  that  pro¬ 
duces  the  color  from  the  lookup  table.  If  it  is  set,  then  the  overlay  plane  deter¬ 
mines  the  pixel’s  color  (black  or  white).  The  effect  is  like  having  a  color  and 
monochrome  display  in  one,  with  the  enable  plane  determining  which  is  shown 
in  each  pixel. 


Read  the  cgf  our  (4s)  manual  page  for  more  information  on  this  frame  buffer  architecture. 
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In  fact,  in  the  color  Sun- 3/60  and  Sun-4/1 10  plane  group  implementations,  you 
can  set  the  colors  in  the  overlay  plane  to  other  that  black  and  white.  There  are 
only  two  colors  in  the  overlay  plane  since  it  is  only  one-bit  deep,  but  they  can 
have  colors  other  than  black  and  white  assigned  to  them. 

Such  sets  of  buffers  are  referred  to  as  plane  groups. 

SunView  and  Plane  Groups  At  the  pixrect  level  it  is  possible  to  manipulate  the  three  plane  groups  of  multiple 

plane  group  framebuffers  directly.  At  the  SunView  level,  some  decisions  have 
been  made  for  you.  Raster  operations  in  the  overlay  plane  are  faster  than  in  the 
color  plane,  so  SunView  objects  which  only  use  the  foreground  and  background 
colors  such  as  frames,  text  subwindows,  panels,  cursors,  menus,  etc.  all  try  to  run 
in  the  overlay  plane.  If  you  set  the  foreground  and  background  explicitly  using 
the  techniques  explained  in  Changing  Colors  from  the  Command  Line  above,  or 
if  you  have  told  sunview  to  run  in  the  color  buffer  only  by  giving  it  the  com¬ 
mand  line  argument  -8bit_jcolor_only,  then  these  objects  wiU  run  in  the 
color  plane. 

However,  canvases  and  graphics  subwindows  default  to  using  the  color  plane 
group  whenever  possible,  on  the  assumption  that  you  want  to  draw  in  color.  If 
this  is  not  the  case,  then  you  may  find  that  your  application  runs  faster  if  you  hint 
to  these  subwindows  to  use  the  overlay  plane: 

o  For  canvases,  set  the  attribute  CANVAS_FAST_jyiONO,  either  when  creating 
the  canvas  or  later,  as  in: 

- ^  , 

window_set  (canvas,  CANVAS_FAST__MONO,  TRUE,  0); 

k _ _ _ J 

If  your  application  uses  scrollbars,  then  you  need  to  set 
CANVAS_FAST_MONO  before  you  create  the  canvas’  scrollbars,  since  they 
share  the  canvas’  pixwin. 

o  For  graphics  subwindows  in  old-style  SunWindows  applications,  use  the 

pixwin  call  pw_use_fast_monochrome  (pw)  as  follows: 

- ^  . 

pw_use_f  ast_monochrome (gfx->gfx_pixwin) ; 

^ - / 


Both  calls  affect  only  multiple  plane  group  displays,  so  it  is  safe  and  desirable  to 
put  them  in  any  Sun  application  that  uses  monochrome  canvases  or  graphics 
subwindows.  Again,  if  the  user  gives  the  appropriate  command  line  arguments, 
canvases  and  graphics  subwindows  wiU  run  in  the  color  plane  regardless  of  these 
calls. 
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“Glitches”  Visible  when  Using 
Plane  Groups 


For  performance  reasons,  the  cursor  image  is  only  written  in  the  plane  group  of 
the  window  under  it.  So,  if  the  cursor’s  hot  spot  is  in  a  black  and  white  window 
in  the  overlay  plane  and  there  is  an  adjacent  color  window,  that  part  of  its  image 
that  would  lie  over  the  color  window  is  invisible,  since  it  is  drawn  in  the  overlay 
plane  but  the  enable  plane  is  stiU  showing  the  value  in  the  color  buffer.  The 
same  disappearance  applies  in  the  reverse  situation. 

When  menus  are  drawn,  the  enable  plane  is  set  so  that  they  are  visible. 


sunview  and  Plane  Groups  It  is  possible  to  direct  sunview(l)  to  only  use  the  color  buffer  or  the  overlay 

plane;  it  is  also  possible  to  start  up  a  second  copy  of  sunview  in  the  other  plane 
group,  and  switch  between  them  using  switcher(l)  or  - 
ad  jacent  screens(l).  Consult  these  programs’  manual  pages  for  more  infor¬ 
mation. 
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Text  Subwindows 


This  chapter  describes  the  text  subwindow  package,  which  you  can  use  by 
including  the  file  <suntool/text  sw .  h>. 

Figure  8-1  is  a  text  subwindow.  A  text  subwindow  allows  a  user  or  client  to 
display  and  edit  a  sequence  of  ASCII  characters.  These  characters  are  stored  in  a 
file  or  in  primary  memory.  Its  features  range  from  inserting  into  a  file  to  search¬ 
ing  for  and  replacing  a  string  of  text  or  a  character. 

Figure  8-1  Text  Subwindow 


textedit  -  (NONE),  dir:  /usr'/topaz/yyonne 
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Summary  Tables 


To  give  you  a  feeling  for  what  you  can  do  with  text  subwindows,  overleaf  there 
is  a  list  of  the  available  text  subwindow  attributes  and  functions.  Many  of  these 
are  discussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to  check). 
All  are  briefly  described  with  their  arguments  in  the  text  subwindow  summary 
tables  in  Chapter  19,  SunView  Interface  Summary: 

□  the  Text  Subwindow  Attributes  table  begins  on  page  366; 

□  the  Text  sw_act  ion  Attributes  table  begins  on  page  370; 
n  the  Texts w_status  Values  table  begins  on  page  37 1 ; 

□  the  Text  Subwindow  Functions  table  begins  on  page  372. 
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Text  Subwindow  Attributes 

TEXT SW  ADJUST  IS  PENDING  DELETE 

TEXTSW_INSERT_FROM_FILE 

TEXTSW_AGAI N_RECORD ING 

TEXTSW_INSERT_MAKES_VISIBLE 

TEXTSW_AUTO__INDENT 

TEXTSW_INSERTION_POINT 

TEXTSW_AUTO_SCROLL_BY 

TEXTSW_LEFT_MARGIN 

TEXTSW_BL INK_CARET 

TEXTSW_LENGTH 

TEXTSW_BROWSING 

TEXTSW_LINE_BREAK_ACT ION 

TEXT  SW_CHECKPO INT_FREQDENCY 

TEXTSW_LOWER_CONTEXT 

TEXTSW_CLIENT_DATA 

TEXTSW_MEMORY_MAXI MUM 

TEXT  SW_CONF IRM_OVERWR I TE 

TEXTSW_MENU 

TEXTSW_CONTENTS 

TEXTSW_MODIFIED 

TEXT  SW  CONTROL  CHARS  USE  FONT 

TEXTSW_MDLT I_CLI CK_SPACE 

TEXTSW_DI SABLE_CD 

TEXTSW_MULT I_CLI CK_T IMEOUT 

TEXTSW_DI SABLE_LOAD 

TEXTSW_NOTIFY_PROC 

TEXTSW_ED I T_COUNT 

TEXTSW_READ_ONLY 

TEXTSW_FILE 

TEXTSW_SCROLLBAR 

TEXTSW_FI LE_CONTENTS 

TEXTSW_STATUS 

TEXTSW_FIRST 

TEXTSW_STORE_CHANGES_FI LE 

TEXTSW_FIRST_LINE 

TEXTSW_STORE_SELF_IS_SAVE 

TEXTSW_HI STORY_LIMIT 

TEXTSW_UPDATE_SCROLLB2\R 

TEXTSW_IGNORE_LIMIT 

TEXTSW_UPPER_CONTEXT 

Textsw_ 

action  Attributes 

TEXTSW_ACTION_CAPS_LOCK 

TEXTSW_ACTI ON_TOOL_CLOSE 

TEXTSW  ACTION_CHANGED_DIRECTORY 

TEXTSW  ACTION_TOOL_DESTROY 

TEXT  SW_ACTI ON_ED I TED_FI LE 

TEXTSW_ACTI  ON__TOOL_QUIT 

TEXTSW  ACTION_EDITED_MEMORY 

TEXTSW  ACTION_TOOL_MGR 

TEXT  SW  ACTION  FILE  IS  READONLY 

TEXTSW_ACTI ON_aS ING_MEMORY 

TEXTSW_ACTION_LOADED_FILE 
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_ Text  Subwindow  Functions _ 

textsw_add._mark  (textsw,  position,  flags) 
textsw_append_f ile_name (textsw,  name) 
textsw_delete (textsw,  first,  last_plus_one) 
textsw_edit (textsw,  unit,  count,  direction) 
textsw_erase (textsw,  first,  last_plus_one) 
textsw_f  ile_lines_visible  (textsw,  top, -^bottom) 

textsw_find_bytes (textsw,  first,  last_jplus_one,  buf,  buf_len,  flags) 
textsw_f ind_mark (textsw,  mark) 
textsw_first (textsw) 

textsw__index_for_f ile_line  (textsw,  line) 

textsw_insert (textsw,  buf,  buf_len) 

text sw_match_bytes (textsw,  first,  last_plus_one, 

start_sym,  start_sym_len,  end_sym,  end_sym_len,  field_flag) 

textsw_next (textsw) 

textsw__normalize_view (textsw,  position) 
textsw_possibly__normalize  (textsw,  position) 
textsw_remove_mark (textsw,  mark) 

textsw_replace_bytes (textsw,  first,  last_plus_one,  buf,  buf_len) 

textsw_reset (textsw,  x,  y) 

textsw_save (textsw,  x,  y) 

textsw_screen_line_count (textsw) 

textsw_scroll_lines (textsw,  count) 

textsw_set_selection (textsw,  first,  last_plus_one,  type) 
textsw  store  file (textsw,  filename,  x,  y) 
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8.1.  Text  Subwindow 
Concepts 


This  section  introduces  the  basic  concepts  of  a  text  subwindow. 


Creating  a  Subwindow 


Attribute  Order 


Determining  a  Character’s 
Position 


Getting  a  Text  Selection 


Editing  a  Text  Subwindow 


You  create  a  text  subwindow  the  same  way  that  you  create  any  SunView  window 
object,  by  calling  the  window  creation  routine  with  the  appropriate  type  parame¬ 
ter: 

- 

Textsw  textsw; 

textsw  =  window__create  (base_f  rame,  TEXTSW,  attributes,  0); 

. _ ^ _ / 


The  attributes  in  the  above  call  constitute  an  attribute  list  which  is  discussed  in  a 
Section  later  in  this  chapter,  titled  Attribute-based  Functions. 


Most  attributes  are  orthogonal;  thus  you  usually  need  not  worry  about  their  order. 
However,  in  a  few  cases  the  attributes  in  a  list  may  interact,  so  you  need  to  be 
careful  to  specify  them  in  a  particular  order.  Such  cases  are  noted  in  the  sections 
which  foUow."^^  In  particular,  you  must  pass  TEXTSW_STATUS  first  in  any  call 
to  window_cr  eate  ( )  or  window_set  ( )  if  you  want  to  find  the  status  after 
setting  some  other  attribute  in  the  same  call. 

The  contents  of  a  text  subwindow  are  a  sequence  of  characters.  At  any  moment, 
each  character  can  be  uniquely  identified  by  its  position  in  the  sequence  (t3q)e 
Textsw_index).  Editing  operations,  such  as  inserting  and  deleting  text,  cause 
the  index  of  any  particular  character  to  change  over  time.  The  valid  indices  are  0  V. 
through  length-1  inclusive,  where  length  is  the  number  of  characters  currently  in 
the  text  subwindow,  returned  by  the  textsw_length  attribute. 

The  text  subwindow  has  a  notion  of  the  current  index  after  which  the  next  char¬ 
acter  will  be  inserted  at  any  given  moment.  This  is  called  the  insertion  point.  A 
caret  is  drawn  on  the  screen  immediately  after  this  index  to  give  the  user  a  visual 
indication  of  the  insertion  point. 

A  text  selection  is  made  by  the  user,  and  it  is  indicated  oh  the  screen  with 
reverse- video  highlighting.  A  text  subwindow  function  or  procedure  is  not  used 
to  determine  which  window  has  the  current  selection  or  to  retrieve  information 
contained  in  a  text  subwindow.  Instead,  these  functions  are  carried  out  by  the 
Selection  Service.  For  an  example  of  how  this  is  done,  refer  to  Section  16,  The 
Selection  Service. 


A  text  subwindow  may  be  edited  by  the  user,  or  by  a  client  program.  When  you 
create  a  text  subwindow,  by  default  the  user  can  edit  it.  By  using  the  special 
attributes  discussed  in  this  section,  the  client  program  can  edit  the  subwindow. 
These  edits  are  then  stored  in  /tmp /textProcess-id.Counter. 

The  following  five  sections  explain  the  functions  and  attributes  that  you  wiU  use 
to  load,  read,  write,  edit,  and  finally  save  a  text  file. 


For  a  discussion  of  attribute  ordering  in  general,  see  Section  4.8,  Attribute  Ordering. 
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8.2.  Loading  a  File  You  can  load  a  file  into  a  textsw  by  using  TEXTSW_FILE ,  as  in: 

- , 

window_set (textsw,  TEXTSW_FILE,  file_name,  0); 

_ _ 

Keep  in  mind,  that  if  the  existing  text  has  been  edited,  then  these  edits  will  be 
lost.  To  avoid  such  loss,  first  check  whether  there  are  any  outstanding  edite  by 
calling: 

—  , 

window_get (textsw,  TEXTSW_MODIFIED) 


The  above  call  to  window_set  ( )  will  load  the  new  file  with  the  text  posi¬ 
tioned  so  that  the  first  character  displayed  has  the  same  index  as  the  first  charac¬ 
ter  that  was  displayed  in  the  previous  file  —  which  is  probably  not  what  you 
want.  To  load  the  file  with  the  first  displayed  character  having  its  index  specified 
by  position,  use  the  following: 

- -  , 

window_set (textsw,  TEXTSW_FILE,  file_name, 

TEXTSW_FIRST,  position,  0) ; 

_ — - 


NOTE  The  order  of  these  attributes  is  important.  Because  attributes  are  evaluated  in 

the  order  given,  reversing  the  order  would  first  reposition  the  existing  file,  then 
load  the  new  file.  This  would  cause  an  unnecessary  repaint,  and  mis-position  the 
old  file,  if  it  was  shorter  than  position.  For  a  full  discussion  of  attribute  ord¬ 
ering,  see  Section  8.5. 

Both  of  the  above  calls  blindly  trust  that  the  load  of  the  new  file  was  successful. 
This  is,  in  general,  a  bad  idea.  To  find  out  whether  the  load  succeeded,  and  if 
not,  why  not,  use  the  following  call: 

- —  ^ 

window_set (textsw, 

TEXTSW_STATUS,  & status, 

TEXTSW_FILE,  file_name, 

TEXTSW_FIRST,  position, 

0)  ; 

- - 

where  status  is  declared  to  be  of  type  Text  sw_status. 

NOTE  The  TEXTS W_STATUS  attribute  and  handle  must  appear  in  the  attribute  list 
before  the  operation  whose  status  you  want  to  determine. 

Text  sw  status  Value  The  valid  values  for  such  a  variable  are  enumerated  in  the  following  table,  where 

~  the  common  prefix  TEXTSW_STATUS_  has  been  removed.  For  example,  OKAY 

in  the  table  is  actuaUy  textsw_STATUS_OKAY. 


Checking  the  Status  of  the 
Text  Subwindow 
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Table  8-1  Textsw 

status  Values 

Value 

Description 

TEXTSW_STATUS_OKAY 

The  operation  encotmtered  no  problems. 

TEXTSW_STATUS_BAD_ATTR 

The  attribute  list  contained  an  illegal  or  unrecognized  attribute. 

TEXTSW_STATUS_BAD_ATTR_VALUE 

The  attribute  list  contained  an  illegal  value  for  an  attribute, 
usually  an  out  of  range  value  for  an  enumeration. 

TEXTSW_STATUS_CANNOT_ALLOCATE 

A  call  to  calloc(2)  or  malloc(2)  failed. 

TEXTSW_STATUS_CANNOT_OPEN_INPUT 

The  specified  input  file  does  not  exist  or  cannot  be  accessed. 

TEXTSW_STATUS_CANNOT_INSERT_FROM_FILE 

The  operation  encountered  a  problem  when  trying 
to  insert  from  file. 

TEXTSW_STATUS_OUT_OF_MEMORY 

The  operation  ran  out  of  memory  while  editing  in  manory. 

TEXTSW_STATUS_OTHER_ERROR 

The  operation  encountered  a  problem  not  covered  by  any  of 
the  othCT  error  indications. 

8.3.  Writing  to  a  Text  To  insert  text  into  a  text  subwindow  at  the  current  insertion  point,  call: 

Subwindow  „  ^  , 

Text  sw_index 

textsw_insert (textsw,  buf ,  buf_len) 

Textsw  textsw; 
char  *buf; 
int  buf_len; 

The  return  value  is  tlte  number  of  characters  actually  inserted  into  the  text 
subwindow.  This  number  will  equal  buf_len  unless  either  die  text  subwindow 
has  had  a  memory  allocation  failure,  or  the  portion  of  text  containing  the  inser¬ 
tion  point  is  read  only.  The  insertion  point  is  moved  forward  by  the  number  of 
characters  inserted. 


NOTE  This  routine  does  not  do  terminal-style  interpretation  of  the  input  characters. 

Thus  “editing”  characters  (such  as  CTRL-H  or  del  for  character  erase,  etc.)  are 
simply  inserted  into  the  text  subwindow  rather  than  performing  edits  to  the  exist¬ 
ing  contents  of  the  text  subwindow.  In  order  to  do  terminal-style  emulation,  you 
must  pre-scan  the  characters  to  be  inserted,  and  invoke  texts  w_edit  ( )  where 
appropriate,  as  described  in  the  next  section. 
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Insertion  Point  The  attribute  TEXTSW_INSERT  I0N_P0INT  is  used  to  interrogate  and  to  set 

the  insertion  point  For  instance,  the  following  call  determines  where  the  inser¬ 
tion  point  is: 

- - - , 

Textsw_index  point; 

point  =  (Textsw_index) window_get (textsw, 

TEXTSW_INSERTION_POINT) ; 

s _ ^ 

whereas  the  following  call  sets  the  insertion  point  to  be  just  before  the  third  char¬ 
acter  of  the  text: 

- - - - 

window_set (textsw,  TEXTSW_INSERTION_POINT,  2,  0) ; 

S _ _ _ 1 - ) 


Positioning  to  End  of  Text  To  set  the  insertion  point  at  the  end  of  the  text,  set 

TEXTSW_INSERTI0N_P0INT  to  the  Special  index  textsw_infinity. 

NOTE  This  call  does  not  ensure  that  the  new  insertion  point  will  be  visible  in  the  text 

subwindoWi  even  if  the  TEXTSW_INSERT_MAKES_VISIBLE  attribute  is 
TRUE,  To  guarantee  that  the  caret  will  be  visible  afterwards,  you  should  caU 
textsw__possiblY_normalize  ( ) . 

8.4.  Reading  from  a  Text  Many  applications  that  incoiporate  text  subwindows  never  need  to  read  the  con- 
Subwindow  tents  of  the  text  directly  from  the  text  subwindow.  Often,  this  is  because  the  text 

subwindow  is  only  being  used  to  display  text  to  the  user. 

Even  when  the  user  is  allowed  to  edit  the  text,  some  applications  simply  wait  for 
the  user  to  perform  some  action  that  indicates  that  aU  of  the  edits  have  been 
made.  They  then  use  either  textsw_save  { )  or  text  sw_store_f  ile  ( }  to 
place  the  text  in  the  file.  The  text  can  then  be  read  via  the  usual  file  input  utili¬ 
ties,  or  the  file  itself  can  be  passed  off  to  another  program. 

It  is,  however,  useful  to  be  able  to  directly  examine  the  text  in  the  text  subwin¬ 
dow.  You  can  do  this  using  the  TEXTSW_CONTENTS  attribute.  The  following 
code  fragment  illustrates  how  to  use  textsw_CONTENTS  to  get  a  span  of  char¬ 
acters  from  the  text  subwindow.  It  gets  the  1000  characters  beginning  at  position 
500  out  of  the  text  subwindow  and  places  them  into  a  nuU-terminated  string. 

♦define  TO_READ  1000 

char  buf [TO_READ+l ] ; 

Textsw_index  next_pos; 

next^os  =  (Textsw_index) 

window_get (textsw,  TEXTSW_CONTENTS,  500,  buf,  TO_READ) ; 

if  (next_pos  1=  500+TO_READ)  { 

Error  case 
}  else 

buf[TO_READ]  =  ’■\0'; 

S _ ! - 
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8.5.  Editing  the  Contents  of  The  file  or  memory  being  edited  by  a  text  subwindow  is  referred  to  as  the  back- 
a  Text  Subwindow  ing  store.  Several  attributes  and  functions  are  provided  to  allow  you  to  manipu¬ 

late  the  backing  store  of  a  text  subwindow.^®  This  section  describes  the  pro¬ 
cedures  and  attributes  that  you  can  use  to  edit  a  text  subwindow. 


Removing  Characters  You  can  remove  a  contiguous  span  of  characters  from  a  text  subwindow  by  cal¬ 

ling: 

Textsw_index 

textsw_delete (textsw,  first,  last_plus_one) 

Textsw  textsw; 

Textsw_index  first,  last_plus_one; 

first  specifies  the  first  character  of  the  span  that  will  be  deleted,  while 
last_plus_one  specifies  the  first  character  after  the  span  that  will  not  be 
deleted,  first  should  be  less  than,  or  equal  to,  last_plus_one.  To  delete 
to  the  end  of  the  text,  pass  the  special  value  textsw_infinity  for 
last_j5lus_one. 

The  return  value  is  the  number  of  characters  deleted,  and  is  last_plus_one 
-  fir  St,  unless  aU  or  part  of  the  specified  span  is  read-only.  In  this  case,  only 
those  characters  that  are  not  read-only  will  be  deleted,  and  the  return  value  will 
indicate  how  many  such  characters  there  were.  If  the  insertion  point  is  in  the 
span  being  deleted,  it  will  be  left  at  fir  st. 

A  side-effect  of  calling  textsw_delete  { )  is  that  the  deleted  characters 
become  the  contents  of  the  global  Clipboard.  To  remove  the  characters  from  the 
textsw  subwindow  without  affecting  Ae  Qipboard,  caU: 

Text  sw_index 

textsw_erase (textsw,  first,  last_plus_one) 

Textsw  textsw; 

Textsw_index  first,  last_plus__one; 

Again,  the  return  value  is  the  number  of  characters  removed,  and 
lastjplus_one  can  be  TEXTSW_INFINITY. 

Both  of  these  procedures  will  return  0  if  the  operation  fails. 

Emulating  an  Editing  You  can  emulate  the  behavior  of  an  editing  character,  such  as  CTRL-H,  with 

Character  textsw_edit  ( ) : 

Text  s w_index 

textsw_edit (textsw,  unit,  count,  direction) 

Textsw  textsw; 

unsigned  unit,  count,  direction; 


^  Note  that  the  edit  log  maintained  by  the  text  subwindow  package  is  reset  on  each  citation  affecting  the 
backing  store.  For  a  desciipticHi  of  the  edit  log,  see  the  discussion  at  the  end  of  Editing  the  Contents  of  a  Text 
Subwindow. 
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Replacing  Characters 


Depending  on  the  value  of  unit,  this  routine  will  erase  either  a  character,  a 
word,  or  a  line.  Set  unit  to: 

□  TEXT SW_UN I T_I S_CH AR  to  erase  individual  characters, 

□  TEXTSW_UNIT_IS_W0RD  to  erase  the  span  of  characters  that  make  up  a 
word  (including  any  intervening  white  space  or  other  non-word  characters), 
or 

□  TEXTSW_UNIT_IS_LINE  to  erase  all  characters  in  the  line  on  one  side  of 
the  insertion  point. 

If  the  direction  parameter  is  0,  the  operation  will  affect  characters  after  the 
insertion  point,  otherwise  it  will  affect  characters  before  the  insertion  point 

The  number  of  times  the  operation  will  be  applied  is  determined  by  the  value  of 
the  count  parameter.  Set  it  to  one  to  do  the  edit  once,  or  to  a  value  greater  than 
one  to  do  multiple  edits  in  a  single  call,  text  sw__edit  ( )  returns  the  number 
of  characters  actually  removed. 

For  example,  suppose  you  want  to  interpret  the  function  key  I F7 1  as  meaning 
“delete  word  forward”.  On  receiving  the  event  code  for  the  1F7 1  key  going  up, 
you  would  make  the  call: 

- ^  , 

textsw_edit (textsw,  TEXTSW_UNIT_IS_WORD,  0) ; 

s _ > 


While  a  span  of  characters  may  be  replaced  by  calling  text  sw_erase  ( )  fol¬ 
lowed  by  text  sw_insert  ( ) ,  character  replacement  is  done  most  efficiently 
by  calling: 

Textsw_index 

textsw_replace_bytes (textsw,  first,  last_plus_one,  buf ,  buf_len> 
Textsw  textsw; 

Textsw_index  first,  last_plus_one; 
char  *buf; 

int  buf_len; 

The  span  of  characters  to  be  replaced  is  specified  by  first  and 
last_plus_one,  just  as  in  the  call  to  text  sw_erase  ( ) .  The  new  charac¬ 
ters  are  specified  by  buf  and  buf_len,  just  as  in  the  call  to 
textsw_insert  ( ) .  Once  again,  if  last_plus_one  is 
TEXTSW_INFINITY,  the  replace  affects  all  characters  from  first  to  the  end 
of  the  text.  If  the  insertion  point  is  in  the  span  being  replaced,  it  will  be  left  at 
first  +  buf_len. 

The  return  value  is  the  net  number  of  bytes  inserted.  The  number  is  negative  if 
the  original  string  is  longer  than  the  one  which  replaces  it.  If  a  problem  occurs 
when  an  attempt  is  made  to  replace  a  span,  then  it  wiU  return  an  error  code  of  0. 

textsw_replace_bytes  (),  like  text  sw_erase  () ,  does  nor  put  the 
characters  it  removes  on  the  global  Qipboard. 
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The  Editing  Log  All  text  subwindows  allow  the  user  to  undo  editing  actions.  In  order  to  imple¬ 

ment  this  feature,  the  text  subwindow  package  keeps  a  running  log  of  aU  the 
edits.  If  there  is  a  file  associated  with  the  text  subwindow,  this  log  is  kept  in  a 
file  in  the  /tmp  directory. 

This  file  can  grow  until  this  directory  runs  out  of  space.  To  limit  the  size  of  the 
edit  log  and  to  avoid  filling  up  all  of  tmp  the  user  can  set  the  tex  wrap  around 
size  in  the  de  fault  s  edit  (1)  Tty/text_wraparound_size.  If  there  is  no  associ¬ 
ated  file,  the  edit  log  is  kept  in  memory,  and  the  maximum  size  of  the  log  is  con¬ 
trolled  by  the  attribute  textsw_memory_maximum,  which  defaults  to  20,000 
bytes. 

Unfortunately,  once  an  edit  log  kept  in  memory  has  reached  its  maximum  size, 
no  more  characters  can  be  inserted  into  or  removed  from  the  text  subwindow.  In 
particular,  since  deletions,  as  well  as  insertions,  are  logged,  space  cannot  be 
recovered  by  deleting  characters. 

It  is  important  to  understand  how  the  edit  log  works  because  you  may  want  to  use 
a  text  subwindow  with  no  associated  file  to  implement  a  temporary  scratch  area 
or  error  message  log.  If  such  a  text  subwindow  is  used  for  a  long  time,  the 
default  limit  of  20,000  bytes  may  well  be  reached,  and  it  will  be  impossible  for 
either  the  user  or  your  code  to  insert  any  more  characters  even  though  there  may 
be  only  a  few  characters  visible  in  the  text  subwindow.  Therefore,  it  is  recom¬ 
mended  to  set  TEXTSW_MEMORY_MAXlMUM  much  higher,  say  to  200,000. 

Which  File  is  Being  Edited?  To  find  out  which  file  the  text  subwindow  is  editing,  caU: 

int 

textsw_append_f ile_name (textsw,  name) 

Textsw  textsw; 
char  *name; 

If  the  text  subwindow  is  editing  memory,  then  this  routine  will  return  a  non-zero 
value.  Otherwise,  it  will  return  0,  and  append  the  name  of  the  file  to  the  end  of 
name. 

Interactions  with  the  File  If  a  text  subwindow  is  editing  a  file  called  my  file  and  the  user  chooses  ‘Save 

System  Current  File’  from  the  subwindow’s  menu  (or  client  code  invokes 

t ext  s w_s  ave  ( ) ),  the  following  sequence  of  file  operations  occurs: 

□  myf  ile  is  copied  to  myf  ile% 

□  The  contents  of  my  f  i  1  e  %  are  combined  with  information  from  the  edit  log 
file  U  tmp /Hey.tProcess-id.  Counter)  and  written  over  myf  ile  (thereby 
preserving  all  its  permissions,  etc). 

□  The  edit  log  file  is  removed  from  /  tmp. 

If  myf  ile  is  a  symbolic  link  to  .Jsome_dir/ otYiQxf.2.1e,  then  the  backup  file 
is  created  as  .Jsome  other file%. 
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8.6.  Saving  Edits  in  a 
Subwindow 


Storing  Edits 


Discarding  Edits 


Keep  in  mind  that  the  user  can  change  the  current  directory  by  selecting  ‘Load 
File’  or  ‘Set  Directory’  from  the  text  subwindow  menu.  If  myf  ile  is  a  relative 
path  name,  then  the  copy  to  myf  ile%  and  the  save  take  place  in  the  current 
directory. 

To  save  any  edits  made  to  a  file  currently  loaded  into  a  text  subwindow  caU: 
unsigned 

textsw_save (textsw,  locx,  iocy) 

Textsw  textsw; 
int  locx,  locy; 

locx  and  locy  are  relative  to  the  upper  left  comer  of  the  text  subwindow  and 
are  used  to  position  the  upper  left  comer  of  the  alert  should  the  save  fail  for  some 
reason — usually  they  should  be  0.  The  return  value  is  0  if  and  only  if  the  save 
succeeded. 

/ 

The  text  subwindow  may  not  contain  a  file,  or  the  client  may  wish  to  place  the 
edited  version  of  the  text  (whether  or  not  the  original  text  came  from  a  file)  in 
some  specific  file.  To  store  the  contents  of  a  text  subwindow  to  a  file  call: 

unsigned 

textsw_store_f ile (textsw,  filename,  locx,  locy) 

Textsw  textsw; 
char  * filename; 
int  locx,  locy; 

Again,  locx  and  locy  are  used  to  position  the  upper  left  comer  of  the  message 
box.  The  return  value  is  0  if  and  only  if  the  store  succeeded. 

NOTE  By  default,  this  call  changes  the  file  that  the  text  subwindow  is  editing,  so  that 
subsequent  saves  will  save  the  edits  to  the  new  file.  To  override  this  policy,  set 
the  attribute  textsw_STORE_CHANGES_file  to  false. 

To  discard  the  edits  performed  on  the  contents  of  a  text  subwindow,  caU: 
void 

textsw_reset (textsw,  locx,  locy) 

Textsw  textsw; 
int  locx,  locy; 

locx  and  locy  are  as  above.  Note  that  if  the  text  subwindow  contains  a  file 
which  has  not  been  edited,  the  effect  of  textsw_reset  is  to  unload  the  file 
and  replace  it  by  memory  provided  by  the  text  subwindow  package;  thus  the  user 
will  see  an  absolutely  empty  text  subwindow.  Alternatively,  if  the  text  subwin¬ 
dow  already  was  editing  memory  then  another,  untouched,  piece  of  primary 
memory  will  be  provided  and  the  edited  piece  will  be  deallocated. 

The  rest  of  this  chapter  describes  the  other  functions  that  are  available  for  text 
subwindows.  These  features  include  setting  the  contents  of  a  subwindow,  setting 
the  primary  selection,  and  how  to  deal  with  multiple  or  split  views. 
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8.7.  Setting  the  Contents  of  You  may  want  to  set  the  initial  contents  of  a  text  subwindow  that  your  applica- 

a  Text  Subwindow  tion  uses.  For  example,  the  SunView  mailt  ool  sets  the  initial  contents  of  the 

composition  window  to  come  up  with  the  headings  To,  Subject,  and  so  on. 

To  set  the  initial  contents  of  a  text  subwindow,  use  one  of  three  attributes: 
TEXTSW_INSERT_FROM_FILE,  TEXTSW_FILE_CONTENTS,  and 
TEXTSW_CONTENTS.  Each  attribute  is  illustrated  in  code  fragments  given 
below. 


TEXTSW_FILE_CONTENTS  The  attribute  TEXTSW_FlLE_CONTENTS  makes  it  possible  for  a  client  to  ini¬ 
tialize  the  text  subwindow  contents  from  a  file  yet  still  edit  the  contents  in 
memory.  The  user  can  return  a  text  subwindow  to  its  initial  state  after  an  editing 
session  by  choosing  ‘Undo  All  Edits’  in  the  text  menu. 

The  following  code  fragment  shows  how  you  would  use  this  attribute. 

- - 

Textsw  textsw; 

char  * filename; 

Text  sw_index  pos ; 

window_set (textsw, 

TEXTSW_FILE_CONTENTS,  filename, 

TEXTSW_FIRST,  pos, 

0); 

^ ^ _ > 


When  the  client  calls  the  undo  routine  and  filename  is  not  a  null  string,  then  it 
wiU  initialize  the  memory  used  by  the  text  subwindow  with  the  contents  of  the 
file  specified  by  filename. 

When  the  client  calls  the  undo  routine  and  the  filename  is  a  null  string,  then  it 
wiU  initialize  the  memory  used  by  the  text  subwindow  with  the  previous  contents 
of  the  text  subwindow. 

TEXTSW_C0NTENTS  TEXTSW_CONTENTS  lets  you  insert  a  text  string  from  memory,  instead  of  a  file, 

into  the  text  subwindow.  The  default  for  this  attribute  is  NULL. 

If  you  use  window_create  ( )  with  this  attribute,  then  it  will  specify  the  initial 
contents  for  a  non-file  text  subwindow. 

If  you  use  window_set  ( )  with  this  attribute  it  will  set  the  contents  of  a  win¬ 
dow  as  in: 

- - 

window_set (textsw,  TEXTSW_CONTENTS,  "text",  0) ; 

< _ > 


If  you  use  window_get  { )  with  this  attribute,  then  you  wiU  need  to  provide 
additional  parameters  as  in: 


f - ^ ^ 

window_get (textsw,  TEXTSW_CONTENTS,  pos,  buf,  buf_len) 


The  return  value  is  the  next  position  to  be  read.  The  buffer  array 
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buf  [  0. .  .buf_len-l  ]  is  filled  with  the  characters  from  textsw  beginning  at 
the  index  pos,  and  is  null-terminated  only  if  there  were  too  few  characters  to  fill 
the  buffer. 

TEXTSW_lNSERT_FROM_FiLE  TEXTSW_INSERT_FR0M_FILE  allows  a  client  to  insert  the  contents  of  a  file 

into  a  text  subwindow  at  the  current  insertion  point.  It  is  the  programming 
equivalent  of  a  user  choosing  ‘Include  File’  from  the  text  menu. 

The  following  code  fragment  is  a  sample  of  using  this  attribute. 
- 

Textsw  textsw; 

Textsw_status  status; 

window_set (textsw, 

TEXTSW_STATUS,  & status, 

TEXTSW_INSERT_FROM_FILE ,  filename , 

0); 

.. _ _ _ > 


Three  status  values  may  be  returned  for  this  attribute  when  the  argument 
TEXTSW_STATUS  is  passed  in  the  same  call  to  window_create  { )  or 
window_set  (} : 

□  TEXTSW_STATUS_OKAY  —  the  operation  was  successful. 

□  TEXT SW_ST ATUS_CANNOT_INSERT_FROM_F  ILE  —  the  operation 
failed 

□  TEXTSW_STATUS_OUT_OF_MEMORY  — ^the  ftmction  cannot  insert  the 
text,  because  it  ran  out  of  memory 


8.8.  Positioning  the  Text 
Displayed  in  a  Text 
Subwindow 


Usually  there  is  more  text  managed  by  the  text  subwindow  than  can  be  displayed 
all  at  once.  As  a  result,  it  is  often  necessary  to  determine  the  indices  of  the  char¬ 
acters  that  are  being  displayed,  and  to  control  exactly  which  portion  of  the  text  is 
being  displayed. 


Screen  Lines  and  File  Lines  When  there  are  long  lines  in  the  text  it  is  necessary  to  draw  a  distinction  between 

two  different  definitions  of  “line  of  text.” 

A  screen  line  reflects  what  is  actually  displayed  on  the  screen.  A  line  begins 
with  the  leftmost  character  in  the  subwindow  and  continues  across  until  either  a 
newline  character  or  the  right  edge  of  the  subwindow  is  encountered.  A  file  line, 
on  the  other  hand,  can  only  be  terminated  by  the  newline  character.  It  is  defined 
as  the  span  of  characters  starting  after  a  newline  character  (or  the  beginning  of 
the  file)  running  through  the  next  newline  character  (or  the  end  of  the  file). 

Whenever  the  right  edge  of  the  subwindow  is  encountered  before  the  newline,  if 
TEXTSW_LINE_BREAK__ACTION  is  TEXTSW_WRAP__AT_CHAR,  the  next 
character  and  its  successors  will  be  displayed  on  the  next  lower  screen  line.  In 
this  case  there  would  be  two  screen  lines,  but  only  one  file  line.  From  the  per¬ 
spective  of  the  display  there  are  two  lines;  from  the  perspective  of  the  file  only 
one.  If,  on  the  other  hand  textsw_line_break_action  is 
TEXTSW_WRAP_AT_WORD,  the  entire  word  will  be  displayed  on  the  next  line. 


microsystems 


Revision  A,  of  May  9, 1988 


142  SunView  1  Programmer’s  Guide 


Absolute  Positioning 


Relative  Positioning 


Unless  otherwise  specified,  all  text  subwindow  attributes  and  procedures  use  the 
file  line  definition. 

NOTE  Line  indices  have  a  zero-origin,  like  the  character  indices;  that  is,  the  first  line 
has  index  0,  not  1. 

Two  attributes  are  provided  to  allow  you  to  specify  which  portion  of  the  text  is 
displayed  in  the  text  subwindow. 

Setting  the  attribute  TEXTSW_first  to  a  given  index  causes  the  first  character 
of  the  line  containing  the  index  to  become  the  first  character  displayed  in  the  text 
subwindow.  Thus  the  following  call  causes  the  text  to  be  positioned  so  that  the 
first  displayed  character  is  the  first  character  of  the  line  which  contains  index 
1000.  This  call  only  positions  one  view  at  a  time: 


f 

- \ 

window_set (textsw,  TEXTSW_FIRST,  1000,  0); 

1 

J 

To  position  aU  of  the  views  in  a  text  subwindow,  use  the  attribute 
TEXTSW_F0R_ALL_VIEWS  as  in  the  following  call: 


window_set (text  sw , TEXTSW_FOR_ALL_VIEWS ,  TRUE , 

s 

TEXTSW_FIRST,  1000,  0) ; 

1 

_ 

Conversely,  the  following  call  retrieves  the  index  of  the  first  displayed  character: 

/ - \ 

index  =  (Textsw_index) window_get (textsw,  TEXTSW_FIRST) ; 
s _ : _ ^ 

A  related  attribute,  useful  in  similar  situations,  is  TEXTSW_FIRST_LINE. 

When  used  in  a  call  on  winciow_set  { )  or  window_get  ( ) ,  the  value  is  a 
file  line  index  within  the  text. 

You  can  determine  the  character  index  that  corresponds  to  a  given  line  index 
(both  zero-origin)  within  the  text  by  calling: 

Text  5  w_inciex 

textsw_index_f or_f ile_line (textsw,  line) 

Textsw  textsw; 
int  line; 

The  return  value  is  the  character  index  for  the  first  character  in  the  line,  so  char¬ 
acter  index  0  always  corresponds  to  line  index  0. 

To  move  the  text  in  a  text  sub  window  up  or  down  by  a  small  number  of  lines, 
call  the  routine: 

void 

textsw_scroll_lines (textsw,  count) 

Textsw  textsw; 
int  count; 

A  positive  value  for  count  causes  the  text  to  scroll  up,  just  as  if  the  user  had 
used  the  left  mouse  button  in  the  scrollbar,  while  a  negative  value  causes  the  text 
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to  scroll  down,  as  if  the  user  had  used  the  right  mouse  button  in  the  scrollbar. 

How  Many  Screen  Lines  are  When  calling  textsw_scroll_lines  { )  you  may  want  to  know  how  many 
in  the  Subwindow?  screen  lines  are  in  the  text  subwindow.  You  can  find  this  out  by  calling: 

int 

textsw_screen_line_count (textsw) 

Textsw  textsw; 


Which  File  Lines  are  Visible?  Exactly  which  file  lines  are  visible  on  the  screen  is  determined  by  calling: 

void 

textsw_file_lines_visible (textsw,  top,  bottom) 

Textsw  textsw; 

int  *top,  *bottom; 

This  routine  fills  in  the  addressed  integers  with  the  file  line  indices  of  the  first  and 
last  file  lines  being  displayed  in  the  specified  text  subwindow. 

Guaranteeing  What  is  Visible  To  ensure  that  a  particular  line  or  character  is  visible,  call: 

void 

textsw_j)ossibly_normalize  (textsw,  position) 

Textsw  textsw; 

Textsw_index  position; 

The  text  subwindow  must  be  displayed  on  the  screen,  before  this  function  will 
work. 

If  the  character  at  the  specified  position  is  already  visible,  then  this  routine 
does  nothing.  If  it  is  not  visible,  then  it  repositions  the  text  so  that  it  is  visible 
and  at  the  top  of  the  subwindow. 

If  a  particular  character  should  always  be  at  the  top  of  the  subwindow,  then  cal¬ 
ling  the  following  routine  is  more  appropriate: 

void 

textsw_normalize_view (textsw,  position) 

Textsw  textsw; 

Textsw_index  position; 


Ensuring  that  the  Insertion  Point  Most  of  the  programmatic  editing  actions  do  not  update  the  text  subwindow  to 

is  Visible  display  the  caret,  even  if  textsw_INSERT_MAKES_visible  is  set.  If  you 

want  to  ensure  that  the  insertion  point  is  visible,  call  something  like 

-  , 

text sw_pos  sibly_normalize (text  sw, 

(Textsw_index)  window_get (textsw,  TEXTSW_INSERTION_POINT)  ; 

^ ^ - 
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8.9.  Finding  and  Matching 
a  Pattern 


Matching  a  Span  of 
Characters 


Matching  a  Specific  Pattern 


A  common  operation  performed  on  text  is  finding  a  span  of  characters  that  match 
some  specification.  The  text  subwindow  provides  several  rudimentary  pattern 
matching  facilities.  This  section  describes  two  fimctions  that  you  may  call  in 
order  to  perform  similar  operations. 

To  find  the  nearest  span  of  characters  that  match  a  pattern,  caU: 
int 

textsw_find__bytes  (textsw,  first,  last_plus_one,  buf, 
buf_len,  flags) 

Textsw  textsw; 

Textsw_index  *first,  *last_plus_one; 
char  *buf; 

uns igned  buf _len ; 

unsigned  flags; 

The  pattern  to  match  is  specified  by  buf  and  buf_len.  The  matcher  looks  for 
an  exact  and  literal  match  —  it  is  sensitive  to  case,  and  does  not  recognize  any 
kind  of  meta-character  in  the  pattern,  first  specifies  the  position  at  which  to 
start  the  search.  If  flags  is  0,  the  search  proceeds  forwards  through  the  text,  if 
1  the  search  proceeds  backwards.  The  return  value  is  -1  if  the  pattern  cannot  be 
found,  else  it  is  some  non-negative  value,  in  which  case  the  indices  addressed  by 
first  and  last_plus_one  will  have  been  updated  to  indicate  the  span  of 
characters  that  match  the  pattern. 

Another  useful  operation  is  to  find  delimited  text.  For  example,  you  might  want 
to  find  the  starting  brace  and  the  ending  brace  in  a  piece  of  code.  To  find  a 
matching  pattern,  call: 

int 

textsw_match_bytes (textsw,  first,  last  plus  one, 

start_sym,  start_syin_len, 
end_syni,  end._sym_len,  field_flag) 

Textsw 
Text  s  w_index 
char 
int 

unsigned 

first  stores  the  starling  position  of  the  pattern  that  you  want  to  search  for. 
last_plus_one  stores  the  cursor  position  of  the  end  pattern.  Its  value  is  one 
position  past  the  text,  s t  ar t_s ym  and  end_s ym  store  the  beginning  position 
and  ending  position  of  the  pattern  respectively.  start_syin_len  and 
end_sym_len  store  starting  and  ending  pattern’s  length  respectively. 

Use  one  of  the  three  field  flag  values  to  search  for  matches: 
TEXTSW_DELIMITER_FORWARD,  TEXTSW_DELIMITER_BACKWARD,  and 
TEXTSW_DELIMITER_ENCLOSE. 

o  TEXTSW_DELlMlTER_FORWARD  begins  from  first  and  searches  for¬ 
ward  until  it  finds  start_sym  and  matches  it  forward  with  end_sym. 


textsw; 

*first,  *last_plus_one; 
*start_sym,  *end_sym; 
start_sym_len,  end_sym_len; 
field_f lag; 
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8.10.  Marking  Positions 


C. 


o  TEXTSW_DELIMITER_BACKWARD  begins  from  first  and  searches 
backward  for  end_sym  and  matches  it  backward  with  start_sym . 

□  TEXTSW_DELlMlTER_ENCLOSE  begins  from  first  and  expands  both 
directions  to  match  start_sym  and  end_sym  of  the  next  level. 

If  no  match  is  found,  then  text  sw_mat  ch_bytes  ( )  will  return  a  value  of 
-1.  If  a  match  is  found,  then  it  wiU  return  the  index  of  the  first  match. 

The  following  code  fragment  is  an  example  of  finding  delimited  text.  Notice  that 
the  f  ield_f  lag  value  is  TEXTSW_DELIMITER_F0RWARD. 

Textsw_index  first,  last_plus_one,  pos; 

first  =  (Textsw_index)  window_get (textsw,  TEXTSW_INSERTION_POINT) ; 
pos  =  textsw_inatch_bytes  (textsw,  fifirst,  &last_plus_one, 

strlen (”*/") , 

" / * " ,  St rlen ("*/”) ,  TEXTSW_DELIMITER_FORWARD )  ; 

if  (pos  >  0)  { 

textsw_set_selection (textsw,  first,  last_plus_one,  1); 
window_set (textsw,  TEXTSW_INSERTION_POINT,  last_plus_one,  0)  ; 
}  else 

(void)  window_bell (textsw) ; 

This  code  searches  forward  from  first  until  it  finds  the  starting  */  and 
matches  it  forward  with  the  next  */.  If  no  match  is  found,  a  beU  wiU  ring  in  the 
text  subwindow. 

Often  a  client  wants  to  keep  track  of  a  particular  character,  or  group  of  characters 
that  are  in  the  text  subwindow.  Given  that  arbitrary  editing  can  occur  in  a  text 
subwindow,  and  that  it  is  very  tedious  to  intercept  and  track  all  of  the  editing 
operations  applied  to  a  text  subwindow,  it  is  often  easier  to  simply  place  one  or 
more  marks  at  various  positions  in  the  text  subwindow.  These  marks  are 
automatically  updated  by  the  text  subwindow  to  account  for  user  and  client  edits. 
There  is  no  limit  to  the  number  of  marks  you  can  add. 

A  new  mark  is  created  by  calling: 

Text  sw_mark 

textsw_add_mark (textsw,  position,  flags) 

Textsw  textsw; 

Textsw_index  position; 
unsigned  flags; 

The  flags  argument  is  either  TEXTSW_MARK_DEFAULTS  or 
TEXTSW_MARK_MOVE_AT_lNSERT.  The  latter  causes  an  insertion  that  occurs 
at  the  marked  position  to  move  the  mark  to  the  end  of  the  inserted  text,  whereas 
the  former  causes  the  mark  to  not  move  when  text  is  inserted  at  the  mark’s 
current  position.  As  an  example,  suppose  that  the  text  managed  by  the  text 
subwindow  consists  of  the  two  fines 

this  is  the  first  line 

not  this,  which  is  the  second 

s _ - 
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Assume  a  mark  is  set  at  position  5  (just  before  the  i  in  is  on  the  first  line)  with 
flags  of TEXTSW_MARK_MOVE_AT_INSERT. 


When  the  user  selects  just  before  the  is  (thereby  placing  the  insertion  point  before 
the  i,  at  position  5)  and  types  an  Bh,  making  the  text  read 

- ^ 

this  his  the  first  line 
not  this,  which  is  the  second 

s _ _ — - - — . . . > 

the  mark  moves  with  the  insertion  point  and  they  both  end  up  at  position  6. 

However,  if  the  flags  had  been  TEXTSW_MARK_DEFAULTS,  then  the  mark 
would  remain  at  position  5  after  the  user  typed  the  h,  although  the  insertion  point 
moved  on  to  position  6. 


Now,  suppose  instead  that  the  user  had  selected  before  the  this  on  the  first  line, 
and  typed  Kep,  making  the  text  read 


( 

Kepthis  is  the  first  line 
not  this,  which  is  the  second 

- - 

1 _ ^ - 

-- 

In  this  case,  no  matter  what  flags  the  mark  had  been  created  with,  it  would  end 
up  at  position  8,  still  just  before  the  i  in  is. 

If  a  mark  is  in  the  middle  of  a  span  of  characters  that  is  subsequently  deleted,  the 
mark  moves  to  the  beginning  of  the  span.  Going  back  to  the  original  scenario, 
with  the  original  text  and  the  mark  set  at  position  5,  assume  that  the  user  deletes 
from  the  /z  in  this  through  the  e  in  the  on  the  first  line,  resulting  in  the  text 


When  the  user  is  done,  the  mark  will  be  at  position  1,  just  before  the  e  in  te. 


The  current  position  of  a  mark  is  determined  by  calling: 

Text  s w_index 

textsw_f ind_mark (textsw,  mark) 

Textsw  textsw; 

Textsw  mark  mark; 


An  existing  mark  is  removed  by  calling: 
void 

textsw_remove_mark (textsw,  mark) 
Textsw  textsw; 

Textsw  mark  mark; 


Note  that  marks  are  dynamically  allocated,  and  it  is  the  client’s  responsibility  to 
keep  track  of  them  and  to  remove  them  when  they  are  no  longer  needed. 


microsystems 


Revision  A,  of  May  9, 1988 


V 


Chapter  8  —  Text  Subwindows  147 


8.11.  Setting  the  Primary  The  primary  selection  may  be  set  by  calling: 

Selection 

void 

textsw_set_selection (textsw,  first,  last_plus_one,  type) 
Textsw  textsw; 

Textsw_index  first,  last j3lus_one; 
unsigned  type; 

A  value  of  1  for  type  means  primary  selection,  while  a  value  of  2  means  secon¬ 
dary  selection,  and  a  value  of  17  is  pending  delete  Note  that  there  is  no  require¬ 
ment  that  all  or  part  of  the  selection  be  visible;  use 

textsw_jpossibly_normalize  ( )  (described  previously  in  Section  8.5, 
Editing  the  Contents  of  a  Text  Subwindow)  to  guarantee  visibility. 

8.12.  Dealing  with  Multiple  By  using  the  ‘Split  View’  menu  operation,  the  user  can  create  multiple  views  of 

Views  the  text  being  managed  by  the  text  subwindow.  Although  these  additional  views 

are  usually  transparent  to  the  client  code  controlling  the  text  subwindow,  it  may 
occasionally  be  necessary  for  a  client  to  deal  directly  with  all  of  the  views.  This 
is  accomplished  by  using  the  following  routines,  and  the  information  that  split 
views  are  simply  extra  text  subwindows  that  happen  to  share  the  text  of  the  origi¬ 
nal  text  subwindow. 

Textsw 

textsw__f  irst  (textsw) 

Textsw  textsw; 

Given  an  arbitrary  view  out  of  a  set  of  multiple  views,  text  sw_f  irst  ( ) 
returns  the  first  view  (currently,  this  is  the  original  text  subwindow  that  the  client 
created).  To  move  through  the  other  views  of  the  set,  call: 

Textsw 

textsw_next (textsw) 

Textsw  textsw; 

Given  any  view  of  the  set,  text  sw_next  ( )  returns  some  other  member  of  the 
set,  or  NULL  if  there  are  none  left  to  enumerate.  The  following  loop  is 
guaranteed  to  process  all  of  the  views  in  the  set: 

for  ( text sw=textsw_f irst (any_split) ; 

*textsw; 

text s w=t ext sw_next (textsw) )  { 

processing  involving  textsw; 

} 

AVhen  you  create  a  text  subwindow  take  into  account  that  your  user  may  split  the 
window.  If  you  do  something  like  try  to  enlarge  the  window,  you  will  run  into 
problems. 
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8.13.  Notifications  from  a  The  text  subwindow  notifies  its  client  about  interesting  changes  in  the 

Text  Subwindow  subwindow’s  or  text’s  state  by  calling  a  notification  procedure.  It  also  calls  this 

procedure  in  response  to  user  actions.  If  the  client  does  not  provide  an  explicit 
notification  procedure  by  using  the  attribute  textsw_notify_proc,  then  the 
text  subwindow  provides  a  default  procedure.  The  declaration  for  this  procedure 
looks  like: 

void 

notify_proc (textsw,  avlist) 

Textsw  textsw; 

Attr_avlist  avlist; 

avlist  contains  attributes  that  are  the  members  of  the  Text  sw_act  ion 
enumeration. 

Your  notification  procedure  must  be  careful  to  either  process  all  of  the  possible 
attributes  that  it  can  be  called  with  or  to  pass  through  the  attributes  that  it  does 
not  process  to  the  standard  notification  procedure.  This  is  important  because 
among  the  attributes  that  can  be  in  the  avlist  are  those  that  cause  the  standard 
notification  procedure  to  implement  the  Front,  Back,  Open,  Close,  and  Quit 
accelerators  of  the  user  interface. 


Here  is  an  example  of  a  client  notify  procedure,  and  a  code  fragment  demonstrat¬ 
ing  how  it  would  be  used: 
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default_textsw_riotify  = 

(void  (*)  0 ) window_get (textsw,  TEXTSW_NOTIFY_PROC} ; 
window  set (textsw,  TEXTSW_NOTIFY_PROC,  client_notify_proc) ; 


The  Text  sw_act  ion  attributes  which  may  be  passed  to  your  notify  procedure 
are  listed  in  the  following  table  (duplicated  in  Chapter  19,  SunView  Interface 
Summary).  Remember  that  they  constitute  a  special  class  of  attributes  which  are 
passed  to  your  textsw  notification  procedure.  They  are  not  attributes  of  the  text 
subwindow  in  the  usual  sense,  and  can  not  be  retrieved  or  modified  using 
window_get  ( )  or  window_set  ( ) . 


Table  8-2  Textsw  act  Lon  Attributes 


Attribute 

Value  Type 

Description 

TEXTSW_ACT I ON_CAP  S_LOCK 

boolean 

The  user  pressed  the  CAPS-lock  function  key  to  change  the 
setting  of  the  CAPS-lock  (it  is  initially  0,  meaning  off). 

TEXTSW_ACT ION_CHANGED_DIRECTORY 

char  * 

The  current  working  directory  for  the  process  has  been 
changed  to  the  directory  named  by  the  provided  string  value. 

TEXTSW  ACTION_EDITED_FILE 

char  * 

The  file  named  by  the  provided  string  value  has  been  edited. 
Appears  once  per  session  of  edits  (see  below). 

TEXTSW_ACTION_EDI TED_MEMORY 

none 

monitors  whether  an  empty  text  subwindow  has  been  edited. 

TEXT  SW_ACT  I  ON_F  I  LE_I  S_READONLY 

char  * 

The  file  named  by  the  provided  string  value  does  not  have 
write  permission. 

TEXTSW  ACTION_LOADED_FILE 

char  * 

The  text  subwindow  is  being  used  to  view  the  file  named 
by  the  provided  string  value. 

TEXTSW_ACTION_TOOL_CLOSE 

(no  value) 

The  fi-ame  containing  the  text  subwindow  should  become 
iconic. 

TEXTSW  ACTION_TOOL_DESTROY 

Event  * 

The  tool  containing  the  text  subwindow  should  exit, 
without  checking  for  a  veto  from  other  subwindows. 

The  value  is  the  user  action  that  caused  the  destroy. 

TEXT  SW_ACT I ON_T OOL_QU I T 

Event  * 

The  tool  containing  the  text  subwindow  should  exit 
normally.  The  value  is  the  user  action  that  caused 
the  exit. 

TEXT  SW_ACT I ON_TOOL_MGR 

Event  * 

The  tool  containing  the  text  subwindow  should  do  the 
window  manager  operation  associated  wifii  the 
provided  event  value. 

TEXTSW  ACTION_USING_MEMORY 

(no  value) 

The  text  subwindow  is  being  used  to  edit  a  string  stored  in 
primary  memory,  not  a  file. 
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The  attribute  TEXTSW_action_EDITED_file  is  a  slight  misnomer,  as  it  is 
given  to  the  notify  procedure  after  the  first  edit  to  any  text,  whether  or  not  it 
came  from  a  file.  This  notification  only  happens  once  per  session  of  edits,  where 
notification  of  TEXTSW_action_loaded_file  is  considered  to  terminate 
the  old  session  and  start  a  new  one. 

NOTE  The  attribute  TEXTSW_ACTION_LOADED_FILE  must  be  treated  very  care¬ 
fully.  This  is  because  the  notify  procedure  gets  called  with  this  attribute  in 
several  situations:  after  a  file  is  initially  loaded,  after  any  successful  ‘Save 
Current  File’  menu  operation,  after  a  'Undo  All  Edits’  menu  operation,  and  dur¬ 
ing  successful  calls  to  textsw_reset  ( ) ,  textsw_save  ( )  and 
text sw_s tore () . 

The  appropriate  response  by  the  procedure  is  to  interpret  these  notifications  as 
being  equivalent  to: 

“The  text  subwindow  is  displaying  the  file  named  by  the  provided 
string  value;  no  edits  have  been  performed  on  the  file  yet.  In  addition, 
any  previously  displayed  or  edited  file  has  been  either  reset,  saved,  or 
stored  under  another  name.” 
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Panels 


This  chapter  describes  the  panel  subwindow  package,  which  you  can  use  by 
including  the  file  <suntool/ panel .  h>. 

Section  1  provides  a  non-technical  introduction  to  panels.  Section  2  introduces 
the  basic  concepts  and  routines  needed  to  use  panels.  Scrollable  panels  are 
covered  in  Section  3.  Sections  4  through  9  describe  the  different  types  of  panel 
items  in  detail,  including  examples. 

For  examples  of  complete  panels,  see  the  programs  )i/cr,  imagejbrowser  j  and 
image  browser^,  which  are  listed  in  Appendix  A  and  discussed  in  Chapter  4, 
Using  Windows. 

For  quick  reference,  the  next  two  pages  are  a  visual  index  to  the  different  effects 
possible  in  panels.  After  that  come  lists  of  the  available  panel  and  panel  item 
attributes,  functions  and  macros.  Many  of  these  are  discussed  in  the  rest  of  this 
chapter  and  elsewhere  (use  the  Index  to  check).  Finally,  tables  that  summarize 
the  usage  of  panel  attributes,  functions  and  macros  are  in  Chapter  19,  SunView 
Interface  Summary: 

□  the  Panel  Attributes  table  begins  on  page  346; 

□  the  Generic  Panel  Item  Attributes  table  begins  on  page  347; 

o  the  Choice  and  Toggle  Item  Attributes  table  begins  on  page  349; 

□  the  Slider  Attributes  table  begins  on  page  35 1 ; 

□  the  Text  Item  Attributes  table  begins  on  page  352; 

□  the  Panel  Functions  and  Macros  table  begins  on  page  353. 


Quick  Reference,  Listings  and 
Summary  Tables 
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Page  Description 

167  Messages 

168  Buttons 

173  Choice  (default) 

173  Choice  (custom  marks) 

173  Choice  (inverted) 

174  Choice  (current) 

174  Choice  (cycle) 

175  Choice  (dial) 

175  Choice  (images,  menu) 

1 7 1  Choice  (images) 


Example 


This  action  y111  cause  unsaved  edits  to  be  lost. 


[Reset] 


[  Reset  ] 


Drauing  Mode: 
Drauing  Mode: 

Drauing  Mode: 


B  Line 

Q  Rectangle 

@  Cl rcle 

Q  Text 

>  LI  ne 

Rectangle 

Circle 

Text 

Points  I  hum  Rectangle  Circle  Text 


Drauing  Mode:  Line 


Drauing  Mode:  ^.<^L1ne 


Rect 


Line 

Points 


Circle 

Text 


Drawing  Mode 


^sun 
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Page  Description 


Example 


177  Toggle  (vertical) 


178  Text 


Format  Options: 

^  Long 
□  Reverse 

Show  all  files 

Name:  Eduard  G.  Robinson 


179  Text  (masked) 


Passuord:  ******** 


183  Text  with  menu 


File:  dervish. Image 


ESC  >  Filename  completion 


mt 


''S  -  store  Image  to  file 
-  Brouse  directory 
■'Q  -  Quit  _ 


185  Slider 


Brightness:  [75] 


168  Button  with  menu 


Introduction 

Pixulns 

Cursors 

SunVIeu  Model 

Text  Subul ndous 

Icons 

Ml  ndous 

Panels 

1  Scrollbars 

Canvases 

TTY  Subul ndous 

Selection  Service 

Input 

Menus 

Motif 1 er 

Sun 


194  Buttons  with  menus 
on  scrollable  panel 
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Panel  Attributes 

PANEL_ACCEPT_KEYSTROKE 

PANEL_EVENT_PROC 

PANEL  LABEL  BOLD 

PANEL_BACKGROUND_PROC 

PANEL_FIRST__ITEM 

PANEL  LAYOUT 

PANEL_BLINK_CARET 

PANEL  ITEM  X  GAP 

PANEL  SHOW  MENU 

PANEL_CARET_ITEM 

PANEL_ITEM_Y_GAP 

Generic  Panel  Item  Attributes 

PANEL_ACCEPT_KEYSTROKE 

PANEL_MENU_CHOICE  IMAGES 

PANEL_CLIENT_DATA 

PANEL_MENU_CHOI CE_STRINGS 

PANEL_EVENT_PROC 

PANEL_MENU_CHOICE  VALUES 

PANEL_I TEM_RECT 

PANEL_MENU_T I TLE_FONT 

PANEL_ITEM_X 

PANEL_MENU_T I TLE_IMAGE 

PANEL_ITEM_Y 

PANEL_MENU_TITLE_STRING 

PANEL_LABEL_X 

PANEL_NEXT_ITEM 

PANEL_LABEL_Y 

PANEL_NOTIFY  PROC 

PANEL_LABEL_BOLD 

PANEL  PAINT 

PANEL_LABEL_FONT 

PANEL_PARENT_PANEL 

PANEL_LABEL_IMAGE 

PANEL_SHOW_I TEM 

PANEL_LABEL_STRING 

PANEL_SHOW_MENU 

PANEL_LAYOUT 

PANEL_VALUE_X 

PANEL_MENU_CHOICE  FONTS 

PANELVALUE  Y 

1  Choice  and  Toggle  Item  Attributes 

PANEL_CHOI CE_FONTS 

PANEL_MARK  IMAGE 

PANEL_CHOI CE_IMAGE 

PANEL_MARK_IMAGES 

P ANEL_CHOI CE_IMAGE  S 

PANEL_MARK_X 

PANEL__CHOICE_STRING 

PANEL_MARK  XS 

PANEL_CHOI CE_STRINGS 

PANEL_MARK  Y 

PANEL_CHOICE_X 

PANEL_MARK  YS 

PANEL_CHOICE_XS 

PANEL_MENU  MARK  IMAGE 

PANEL_CHOICE_Y 

PANEL_MENU_NOMARK_IMAGE 

PANEL_CHOICE_YS 

PANEL_NOMARK_IMAGE 

PANEL_CHOICES_BOLD 

PANEL_NOMARK_IMAGES 

PANEL_DI SPLAY_LEVEL 

PANEL_SHOW_MENU_MARK 

PANEL_FEEDBACK 

PANEL_TOGGLE_VALUE 

PANEL_LAYOUT 

PANEL_VALUE 

Slider  Item  Attributes 

PANEL_MIN_VALUE 

PANEL_SHOW_RANGE 

PANEL_yALUE 

PANEL_MAX_VALUE 

PANEL_SHOW__VALUE 

PANEL_VALUE  FONT 

PANEL_NOTIFY_LEVEL 

PANEL_SLIDER_WIDTH 

Xr  microsysteiTis 
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Text  Item  Attributes 


PANEL_MASK_CHAR 
PANEL_NOT IFY_LEVEL 
PANEL_NOT IFY_STRING 
PANEL  VALUE  STORED  LENGTH 


PANEL_VALUE_D I SPLAY_LENGTH 

PANEL_VALOE 

PANEL  VALUE  FONT 


Panel  Functions  and  Macros 


panel_accept_key (object,  event) 

panel_accept_menu (object ,  event) 

pane l_accept_p re view (object,  event) 

panel_advance_caret (panel) 

panel_back.up_caret  (panel) 

panel_begin_preview (object ,  event) 

panel  but ton_image (panel,  string,  width,  font) 

panel_cancel__preview (object,  event) 

panel_create_item (panel,  iteni_type,  attributes) 

panel_default_handle_event (object,  event) 

panel_destroY_item  ( item) 

panel_each_item (panel,  item) 

pane l_event (panel,  event) 

panel_get (item,  attribute [,  optional_arg] ) 
panel_get_value (item) 

panel_paint (panel_object,  paint_behavior) 
panel_set (item,  attributes) 
panel_set_value (item,  value) 
panel_t ext_not if y ( item,  event ) 
panel_update_preview (object ,  event) 
panel_update_scrolling_size (panel) 
panel  window_e vent (panel,  eventj _ 


Asun 
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9.1.  Introduction  to  Panels  Panels  contain  items  through  which  the  user  interacts  with  a  program.  Panels  are 
and  Panel  Items  quite  flexible;  you  can  use  them  to  model  a  variety  of  things,  including; 

□  a  form  consisting  mainly  of  text  items; 

□  a  message  window  containing  status  or  error  messages; 

o  a  complex  control  panel  containing  items  and  menus  of  many  types. 

Panels  need  not  be  limited  to  the  size  of  the  subwindow  they  appear  in.  By 
attaching  scrollbars  to  a  panel,  you  can  show  a  large  panel  within  a  smaller 
subwindow.  The  user  can  then  bring  the  area  of  interest  into  view  by  means  of 
the  scrollbars. 

There  are  six  basic  types  of  panel  items:  messages,  buttons,  choices,  toggles, 
text  and  sliders.  Items  are  made  up  of  one  or  more  displayable  components.  One 
component  shared  by  all  item  types  is  the  Ic^el.  An  item  label  is  either  a  string 
or  a  graphic  image  (i.e.,  a  pointer  to  a  pixrect).  Button,  choice,  toggle,  and  text 
items  also  have  a  menu  component.  Thus  the  user  may  interact  with  most  items 
in  either  of  two  ways:  by  selecting  the  item  directly  or  by  selecting  from  the 
item’s  menu. 

Each  item  type  is  introduced  briefly  below. 

Message  Items  The  only  visible  component  of  a  message  item  is  a  label,  which  may  be  an  image 

or  a  string  in  a  specified  font.  Message  items  are  useful  for  annotations  of  all 

kinds,  including  titles,  comments,  descriptions,  pictures,  and  dynamic  status  mes-  ^  j 

sages. 

Message  items  are  selectable,  and  you  may  specify  a  notify  procedure  to  be 
called  when  the  item  is  selected. 


Button  Items 


Choice  Items 


Button  items  allow  the  user  of  a  program  to  initiate  commands.  Buttons,  like 
message  items,  have  a  label,  are  selectable,  and  have  a  notify  procedure.  Button 
items  differ  from  message  items  in  that  they  have  visible  feedback  for  preview¬ 
ing  and  accepting  the  selection. 


Choice  items  allow  the  user  to  select  one  choice  from  a  list.  The  displayed  form 
of  a  choice  item  can  vary  radically,  depending  on  how  you  set  its  attributes.  A 
choice  item  can  be  presented  as: 

□  a  horizontal  or  vertical  list  of  choices,  with  aU  choices  visible  and  the  current 
choice  indicated  by  a  mark  (such  as  a  checkmark); 

□  a  horizontal  or  vertical  list  of  choices,  with  aU  choices  visible  and  the  current 
choice  in  reverse- video; 


□  a  “cycle  item”,  or  list  of  choices  with  only  the  current  choice  visible.  Select¬ 
ing  the  item  causes  the  next  choice  in  the  list  to  be  selected  and  displayed; 


□  a  dial,  knob  or  switch  with  a  pointer  of  some  sort  which  turns  to  indicate  one 
of  several  choices; 


a  place  holder  for  a  pop-up  menu,  with  only  the  label  visible  until  the  menu 
button  is  pressed. 
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Behind  this  flexibility  of  presentation  lies  a  uniform  structure  consisting  of  a 
label,  a  list  of  choices,  and,  optionally,  a  corresponding  lists  of  on-marks  and 
off-marks  used  to  indicate  which  choice  is  currently  selected. 

Toggle  Items  In  appearance  and  stmcture,  toggle  items  are  identical  to  choice  items.  The 

difference  lies  in  the  behavior  of  the  two  types  of  items  when  selected.  In  a 
choice  item  exactly  one  element  of  the  list  is  selected,  or  current,  at  a  time.  A 
toggle  item,  on  the  other  hand,  is  best  tmderstood  as  a  list  of  elements  which 
behave  as  toggles:  each  choice  may  be  either  on  or  off,  independently  of  the 
other  choices.  Selecting  a  choice  causes  it  to  change  state.  There  is  no  concept 
of  a  single  current  choice;  at  any  given  time  aU,  some,  or  none  of  the  choices 
may  be  selected. 

Text  Items  Text  items  are  basically  type-in  fields  with  optional  labels  and  menus.  You  can 

specify  that  your  notify  procedure  be  called  on  each  character  typed  in,  only  on 
specified  characters,  or  not  at  all.  This  allows  an  application  such  as  a  forms- 
entry  program  to  process  input  on  a  per  character,  per  field,  or  per  screen  basis. 

Slider  Items  Slider  items  allow  the  graphical  representation  and  selection  of  a  value  within  a 

range.  They  are  appropriate  for  situations  where  it  is  desired  to  make  fine  adjust¬ 
ments  over  a  continuous  range  of  values.  A  familiar  model  would  be  a  horizontal 
volume  control  lever  on  a  stereo  panel. 

9.2.  Basic  Panel  Routines  This  section  covers  basic  panel  usage,  including  creating  and  sizing  panels,  creat¬ 
ing  and  positioning  panel  items,  modifying  and  retrieving  the  attributes  for 
panels  and  panel  items,  and  destroying  panel  items. 

Creating  and  Sizing  Panels  Like  all  windows  in  SunView,  panels  are  created  by  calling  the  window  creation 

routine  with  the  appropriate  type  parameter: 


r  — 

> 

Panel  panel; 

panel  =  window  create (frame,  PANEL,  0); 

s - ^ - - - 

J 

The  above  call  will  produce  a  panel  which  extends  to  the  bottom  and  right  edges 
of  the  frame.  You  can  specify  the  panel’s  dimensions  explicitly  in  character 
units  via  WlN_COLUMNS  and  WIN_R0WS,  or  in  pixel  units  via  WIN_WIDTH 
and  WIN  HEIGHT.51 


For  a  fuller  discussion  of  subwindow  si2ing  and  layout  see  are  in  Chapter  4,  Using  Windows. 


A 
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Creating  and  Positioning 
Panel  Items 


Explicit  Item  Positioning 


Often  you  want  the  panel  to  be  just  high  enough  to  encompass  aU  of  the  items 
within  it.  After  creating  all  of  the  items,  and  before  creating  any  other  subwin¬ 
dows  in  the  frame,  set  the  height  of  the  panel  by  calling  the  macro 
window_f  it_height  ( ) .  This  macro  will  compute  the  lowest  point  occu¬ 
pied  by  any  of  the  panel’s  items  and  set  the  panel  height  to  that  point  plus  a  bot¬ 
tom  margin  of  four  pixels.  The  macros  window_f  it_width  ( )  to  set  the 
width,  and  window_f  it  ( )  to  set  both  the  height  and  the  width,  are  also  pro¬ 
vided. 

To  create  a  panel  item,  call: 

Panel_item 

panel_create_item (panel,  itein_type,  attributes) 

Panel  panel; 

<item  type>  item_type ; 

<attribute-list>  attributes; 

Values  for  item_type  must  be  one  of  PANEL_MESSAGE,  PANEL_BUTT0N, 
PANEL_CHOICE,  PANEL_CYCLE,  PANEL_TOGGLE,  PANEL_TEXT,  or 
PANEL_SLIDER. 

The  position  of  items  within  the  panel  may  be  specified  explicitly  by  means  of 
the  attributes  panel_item__x  and  panel_item_y.^2  panel_item_x  sets 
the  left  edge  of  the  item’s  rectangle  (the  rectangle  which  encloses  the  item’s  label 
and  value).  panel_item_y  sets  the  top  edge  of  the  item’s  rectangle. 

All  coordinate  specification  attributes  interpret  their  values  in  pixel  units.  For 
simple  panels  and  forms  which  do  not  make  heavy  use  of  images  and  have  only 
one  text  font,  it  is  usually  more  convenient  to  specify  positions  in  character  units 
—  columns  and  rows  rather  than  x’s  and  y ’s.  You  can  specify  positions  in  char¬ 
acter  units  with  the  ATTR_ROW  ( )  and  ATTR_COL  ( )  macros,^^  which  interpret 
tiieir  arguments  as  rows  or  columns,  respectively,  and  convert  the  value  to  the 
corresponding  number  of  pixels,  based  on  the  panel’s  font,  as  specified  by 
WIN_F0NT.  Compare  the  two  caUs  below: 


- ^ 

panel_create_item (panel,  PANEL  MESSAGE, 

PANEL^LABEL  STRING, 

"Hi! ", 

PANEL_ITEM_X, 

10, 

PANEL  ITEM  Y, 

20, 

0); 

v _ 

J 

Many  attributes,  such  as  those  relating  to  iton  positioning,  a[^ly  across  aU  of  the  item  t)^s;  these  are 
called  generic  attributes.  A  comprehensive  surtunaiy  of  these  generic  attributes  is  given  in  the  Generic  Item 
Attributes  table  in  are  in  Chapter  19,  SunView  Interface  Summary. 


ATTR  ROWO  andATTR_COLO  are  described  fully  in  Chapter  18,  AWrihrrie  t/ii/iricj. 
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- — - - , 

panel_creatG_item {panel ,  PANEL_MESSAGE, 

PANEL_LABEL_STRING,  "Hi ! " , 

PANEL_ITEM_X ,  ATTR_COL (10> , 

PANEL_ITEM_y ,  ATTR_ROW (2  0) , 

0); 

< _ _ _ _ _ ' 


The  first  will  place  the  item  at  pixel  location  (10,20),  while  file  %cond  will  place 
the  item  at  row  20,  column  10. 

l<fOTE  The  value  computed  for  ATTR_ROW  ( )  includes  the  top  margin,  given  by 

WIN_T0P_MARGIN,  and  the  value  computed  for  attr_COL  { )  includes  the 
left  margin,  given  by  WIN_LEFT_MARGIN.  The  alternate  macros 
ATTR_ROWS  ( )  and  ATTR_COLS  ( )  are  also  provided,  which  compute  values 
that  do  not  include  the  margins. 

Default  Item  Positioning  If  you  create  an  item  without  specifying  its  position,  it  is  placed  just  to  the  ri^ 

of  the  item  on  the  “lowest  row”  of  the  panel,  where  lowest  row  is  defined  as  the 
maximum  y-coordinate  ( P  ANEL_ITEM_Y  )  of  ^  the  items.  So  in  the  absence 
of  specific  instructions,  items  will  be  placed  within  the  panel  in  reading  order  as 
they  are  created:  beginning  four  pixels  in  from  the  left  and  four  pixels  down 
from  die  top,  items  are  located  from  left  to  right,  top  to  bottom.  If  an  item  wiU 
not  fit  on  a  row,  and  more  of  the  item  would  be  visible  on  the  next  row,  it  will  be 
placed  on  the  next  row.  The  number  of  pixels  left  blank  between  items  on  a  row 
may  be  specified  by  PANEL_ITEM_X_GAP,  which  has  a  default  value  of  10. 
The  number  of  pixels  left  blank  between  rows  of  items  may  be  specified  by 
PANEL_ITEM_Y_GAP,  whichhas  a  default  value  of  5. 

The  default  position  for  the  next  item  is  computed  after  an  itan  is  created.  But  if 
a  client  calls  panel_set  ( )  after  creating  an  item  in  such  a  way  that  the 
enclosing  rectangle  of  the  item  is  altered,  the  default  position  for  the  next  item 

wiU  not  be  recomputed.  So,  for  example, 

- -  , 

item  =  panel_create_item (panel ,  PANEL_MESSAO: ,  0); 
panel_set  (item,  PANEL_LABEL_STRING,  "Hi",  0); 

iteml  =  panel_create_item (panel,  PANEL_MESSAGE, 

PANEL_LABEL_STRING,  "There", 

0); 

^ _ _ _ 


wiU  result  in  There  overlapping  Hi. 

CAUTION  Choice  items  currently  have  problems  with  item  “creep.”  Each  time  the  label 

of  a  choice  item  is  set,  the  position  of  the  item  will  be  evaluated.  If  the  v^ue’s 
position  has  not  been  fixed  (with  value_X/y),  the  value  is  positioned  after  the 
label.  The  problem  is  that  the  label  is  baseline-adjusted  for  a  choice  item.  If  the 
item  position  is  not  given  when  the  label  is  set,  the  choice  item  will  creep  down 
because  of  the  baseline  adjustment. 
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Laying  Out  Components  Within  You  may  also  specify  the  layout  of  the  various  components  within  an  item,  by 
an  Item  means  of  the  attributes  PANEL_LABEL_x,  PANEL_label_Y, 

PANEL_VALUE_x,  PANEL_VALUE_Y,  etc.  If  the  components  are  not  expli¬ 
citly  positioned,  then  the  value  is  placed  either  eight  pixels  to  the  right  of  the 
label,  if  PANEL_LAYOUT  is  PANEL_H0RIZ0NTAL  (the  default),  or  four  pixels 
below  the  label,  if  PANEL_LAYOUT  is  panel_VERTICAL. 

Modifying  Attributes  This  section  describes  how  to  modify  the  values  of  attributes  of  panels  or  indivi¬ 

dual  panel  items  which  have  already  been  created. 

Since  panels  are  a  type  of  window,  their  attributes  are  set  with  window_set  { ) . 
To  set  attributes  of  panel  items,  use: 

panel_set (item,  attributes) 

Panel_item  item; 

<attribute-list>  attributes; 

A  macro  is  provided  to  ease  the  syntax  for  the  common  operation  of  setting  an 
item’s  value  (attribute  PANEL_VALUE  ): 

panel_set_value (item,  value) 

Panel_item  item; 
caddr_t  value; 

Several  examples  of  setting  attributes  are  given  here;  for  a  complete  list  of  the 
attributes  applying  to  panels  and  items,  see  the  tables  in  are  in  Chapter  19,  Sun- 
View  Interface  Summary. 


To  move  a  panel’s  caret  to  the  text  item  name_item: 


To  set  the  value  of  the  choice  item  f  ormat_item  to  the  third  choice  (choices 
are  zero-based): 


The  first  call  below  ereates  a  message  which  is  initially  “hidden”  (not  displayed 
on  the  screen);  the  second  call  displays  the  message: 
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NOTE 


Panel- Wide  Item  Attributes 


NOTE 


Retrieving  Attributes 


The  values  for  string-valued  attributes  are  dynamically  allocated  when  they  are 
set  (at  creation  time  or  later).  If  a  previous  value  was  present,  it  is  freed  after  the 
new  string  is  allocated.  This  is  in  contrast  to  the  storage-allocation  policy  for 
retrieving  attributes,  described  in  the  section  titled  Retrieving  Attributes. 


Some  attributes  which  apply  to  items  may  be  set  for  aU  items  in  the  panel  by  set¬ 
ting  them  when  the  panel  is  created.  Such  attributes  include  whether  items  have 
menus,  whether  item  labels  appear  in  bold,  whether  items  are  laid  out  vertically 
or  horizontally,  and  whether  items  are  automatically  repainted  when  their  attri¬ 
butes  are  modified.^  For  example,  the  caU: 


panel  =  window_create (frame/  PANEL 

PANEL_SHOW_MENU,  FALSE, 
PANEL_LABEL_BOLD,  TRUE, 
PANEL_LAYOUT,  PANEL_VERTICAL, 

PANEL_PAINT,  PANEL_NONE, 

0); 


overrides  the  defaults  for  all  the  attributes  mentioned:  any  items  subsequently 
created  in  that  panel  will  not  have  menus,  will  have  their  labels  printed  in  bold 
and  their  components  laid  out  vertically,  and  will  not  be  repainted  automatically 
when  their  attributes  are  modified. 

When  you  set  the  attribute  PANEL_LAY0UT,  it  will  only  affect  the  components 
in  each  item,  not  the  items  themselves.  That  is,  all  items  in  a  panel  will  not  be 
layed  out  vertically. 

Keep  in  mind  that  he  panel-wide  item  attributes  mentioned  above  are  only  used 
to  supply  default  values  for  items  which  are  subsequently  created.  This  means, 
for  example,  that  you  cannot  change  all  the  item  labels  to  bold  by  first  creating 
the  items  and  then  setting  PANEL_LABEL_BOLD  to  TRUE  for  the  panel. 

Use  window_get  ( )  to  retrieve  attributes  for  a  panel.  To  retrieve  attributes 
applying  to  panel  items,  use: 

caddr_t 

panel_get (item,  attribute!,  optional_arg] ) 

Panel_item  item; 

Panel__attribute  attribute; 

Panel_attribute  optional_arg; 

A  macro  is  provided  to  ease  the  syntax  for  the  common  operation  of  getting  an 
item’s  value  (attribute  panel_value  ): 


^  For  a  complete  list  of  panel-wide  item  attributes,  see  the  Panel  Attributes  table  in  are  in  Chapter  19, 
SunView  Interface  Summary. 
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Destroying  Panel  Items 


caddr_t 

panel_get_value (item,  value) 
Panel_item  item; 
caddr_t  value; 


Since  the  *_get  ( )  routines  are  used  to  retrieve  attributes  of  all  types,  you 
should  coerce  the  value  returned  into  the  type  appropriate  to  the  attribute  being 
retrieved,  as  in  the  examples  below. 


To  find  out  whether  an  item  is  currently  being  displayed  on  the  screen: 


, - - - — - 

int  displayed; 

displayed  =  (int) panel_get (item,  PANEL_SHOW  ITEM) ; 

. 'N 

To  find  out  whether  the  caret  in  a  panel  is  blinking  or  non-blinking: 

int  blinking; 

blinking  =  (int ) window_get (panel,  PANEL_BLINK_CARET) ; 

To  get  the  image  for  a  choice  item’s  third  (counting  from  zero)  choice: 

Pixrect  *iniage; 

image  =  (Pixrect  *)panel_get (item,  PANEL_CHOICE  IMAGE,  2); 

The  above  example  illustrates  the  use  of  the  opt  ional_arg  argument,  which 
is  used  for  only  a  few  item  attributes. 

NOTE  panel_get  ( )  does  not  dynamically  allocate  storage  for  the  values  it  returns. 

If  the  value  returned  is  a  pointer,  it  points  directly  into  the  panel’s  private  data.  It 
is  your  responsibility  to  copy  the  information  pointed  to.  The  policy  for  setting 
attributes  is  different:  the  values  for  string-valued  attributes  are  dynamically 
allocated  (see  the  note  above  under  Modifying  Attributes). 

To  destroy  a  panel  item  (and  free  its  associated  dynamic  storage),  call: 

panel_destroy_item(item)  ; 

Panel  item  item; 
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9.3.  Using  Scrollbars  With 
Panels 

Creating  Scrollbars 


Scrolling  Panels  Which 
Change  Size 


A  scrollable  panel  is  a  large  panel  which  can  be  viewed  through  a  smaller 
subwindow  by  means  of  scrollbars. 

Scrollbars  come  in  two  orientations:  vertical  and  horizontal.  The  call  below 
creates  a  panel  with  both  vertical  and  horizontal  scrollbars  (as  would  be  desirable 

in  a  long,  many-columned  table,  for  example): 

- - - - - , 

panel  =  window_create (frame,  PANEL, 

WIN_VERTICAL_SCROLLBAR,  scrollbar_create (0) , 
WIN_HORIZONTAL_SCROLLBAR,  scrollbar_create (0) , 

0) 


The  values  of  the  attributes  WIN_VERTICAL_SCR0LLBAR  and 

WIN  HORI  Z0NTAL_SCR0LLBAR  are  the  scroUbars  which  are  returned  by  the 

scrollbar_create  {)  calls.^^ 

Commonly  the  scroUbar  will  remain  attached  to  the  panel  for  the  duration  of  the 
panel’s  existence,  and  there  will  be  no  need  to  modify  the  scrollbar’s  attributes. 

In  this  simple  case,  there  is  no  need  to  save  the  handle  returned  by 
scrollbar_create  ( ) .  If  you  desire  to  destroy  the  scrollbar,  modify  its 
attributes,  or  detach  it  from  one  panel  and  attach  it  to  another,  you  must  either 
save  the  handle  or  retrieve  it  from  the  panel.^^  For  example,  to  destroy  a  panel’s 
vertical  scrollbar: 

- - - - 

scrollbar_destroy (panel_get (panel,  WIN_VERTICAL_SCROLLBAR) )  ; 
panel_set (panel,  WIN_VERTICAL_SCROLLBAR,  NULL,  0) ; 


Often  panels  are  used  to  display  information  for  browsing,  iconedit(l),  for 
example,  uses  a  popup  panel  to  allow  the  user  to  browse  through  the  images  in  a 
directory.  The  easiest  way  to  do  this  is  to  create  the  panel  items  anew  each  time 
different  information  is  displayed.  For  example,  the  iconedit  function  which 
fills  the  browsing  panel  first  destroys  any  existing  panel  items,  then  creates  an 
item  for  each  image  found. 

If  you  are  going  to  change  the  size  of  the  panel  in  this  way,  you  must  inform  the 
scrollbar  of  the  new  size  by  calling  the  function: 

panel_update_scrolling_size (panel) 

Panel  panel; 


®  The  call  scrollbarcreate  (0)  produces  a  default  scrollbar.  It  is  usually  best  to  create  a  default 
scrollbar  and  let  the  user  specify  how  it  lodes  via  defaultsedit.  You  can,  of  course,  override  the  user  s  default 
settings  by  explicitly  setting  the  scrollbar’s  attributes.  For  a  complete  list  of  scrollbar  attributes  see  Chapter  19, 
SunView  Interface  Summary. 

“  In  order  to  save  the  scrollbar’s  handle  or  reference  any  scrollbar  attributes  you  must  include  the  file 
<suntool/ scrollbar .h>. 
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Detaching  Scrollbars  from 
Panels 


The  correct  time  to  call  panel_update_scrolling_size  ( )  is  after  you 
have  created  all  the  items  and  given  them  labels.  If  you  don’t  update  the 
scrollbar’s  idea  of  the  panel’s  size,  the  size  of  the  scrollbar’s  bubble  will  be 
wrong. 


You  may  want  the  same  panel  to  be  scrollable  at  one  time,  and  not  scrollable  at 
another.  The  code  fragment  below  illustrates  how  this  can  be  accomplished  by 
attaching  and  detaching  a  scrollbar  from  a  panel: 


^ - — - — 

panel  =  window_create (frame,  PANEL,  0); 

\ 

( create  items,  do  any  other  processing...} 

/*  create  scrollbar  and  attach  it  to  panel  */ 
sb  =  scrollbar_create (0) ; 

panel_set (panel,  WIN_VERTICAL_SCROLLBAR,  sb,  0); 

(panel  functions  with  scrollbar...} 

/*  now  detach  scrollbar  from  panel  */ 
panel_set (panel,  WIN_VERTICAL_SCROLLBAR, 

NULL,  0) ; 

(panel  functions  without  scrollbar...} 

scrollbar_destroy (sb) ; 

1^ 

j 

Note  that  the  two  packages  are  to  be  considered  from  the  application’s  viewpoint 
as  independent  packages  which  can  be  used  together.  The  application,  not  the 
panel  package,  has  the  responsibility  for  creating  any  scrollbars.  In  order  to  free 
the  application  of  the  responsibility  for  destroying  the  scrollbar,  panels,  when 
they  are  destroyed,  destroy  any  scrollbars  attached  to  them.  However,  detaching 
a  scrollbar  from  a  panel,  as  in  the  above  example,  does  not  cause  that  scrollbar  to 
be  destroyed.  The  same  scrollbar  may  be  attached  and  detached  from  any 
number  of  panels  any  number  of  times. 

The  sections  which  follow  discuss  the  six  item  types  in  detail. 


'W 
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9.4.  Messages 


Example 


9.5.  Buttons 
Button  Selection 


Button  Notification 


Messages  are  the  simplest  of  the  item  types.  Their  only  visible  component  is 
their  label.  They  have  no  value  or  menu. 

Message  items,  like  buttons,  are  selectable  and  can  have  notify  procedures.  The 
selection  behavior  of  messages  differs  from  that  of  buttons  in  that  no  feedback  is 
given  to  the  user  when  a  message  is  selected. 


In  the  following  example,  two  message  items  are  used  together  to  give  a  warning 
message: 


This  action  will  cause  unsaved  edits  to  be  lost. 


static  short  stop_array[]  =  { 

♦include  "stopsign. image" 

}; 

mpr  static (stopsign,  64,  64,  1,  stop_array) ; 

panel  create_item (panel ,  PANEL_MESSAGE, 

~  PANEL_LABEL_IMAGE,  & stopsign, 

0); 

panel  create_item (panel,  PANEL_MESSAGE, 
PANEL_LABEL_STRING, 

"This  action  will  cause  unsaved  edits  to  be  lost.", 
0); 


You  may  change  the  label  for  a  message  item  (as  for  any  type  of  item)  via 

PANEL  LABEL  STRING  Or  PANEL_LABEL__IMAGE. 


Button  items  have  a  label  and  a  menu,  but  no  value. 

When  the  left  mouse  button  is  pressed  over  a  button  item,  the  item’s  rectangle  is 
inverted.  When  the  mouse  button  is  released  over  a  button  item,  the  item’s  rec¬ 
tangle  is  painted  with  a  grey  background,  indicating  that  the  item  has  been 
selected  and  the  command  is  being  executed.  The  grey  background  is  cleared 
upon  return  from  the  notify  procedure. 

The  procedure  specified  via  the  attribute  PANEL_NOTlFY_PROC  will  be  called 
when  the  item  is  selected.  The  form  of  the  notify  procedure  for  a  button  is: 

button_notify_proc (item,  event) 

Panel_item  item; 

Event  *event 
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Button  Image  Creation  Utility  A  routine  is  provided  to  create  a  standardized,  button-like  image  from  a  string: 

Pixrect  * 

pane l_button_iinage  (panel,  string,  width,  font) 

Panel  panel; 

char  * St ring; 

int  width; 

Pixfont  *font; 

where  width  indicates  the  width  of  the  button,  in  character  units.  The  value 
returned  is  a  pointer  to  a  pixrect  showing  the  string  with  a  border  drawn  around 
it  If  width  is  greater  than  the  length  of  string,  the  string  will  be  centered  in 
the  wider  border,  otherwise  the  border  will  be  just  wide  enough  to  contain  the 
entire  string  (i.e.,  the  string  will  not  be  clipped).  The  font  is  given  by  font  —  if 
NULL,  the  font  for  panel  is  used. 

Examples  The  first  example  renders  the  string  in  the  default  system  font,  found  in 

/ usr/ lib/ fonts/ f ixedwidthf onts/screen . r . 13: 

(Reset] 


, - - - - - - 

panel_create_item (panel ,  PANEL_BUTTON, 

PANEL_NOTIFY_PROC,  quit_proc, 

PANEL_LABEL_IMAGE,  panel_button_iinage  (panel ,  "Reset”,  0,  0), 
0); 

V - - -  ^ 

The  button  below  has  a  bold  font  and  a  seven  character  wide  border: 

(  Reset  1 

- — ^ 

bold  =  pf_open  ("/usr/l±b/fonts/fixedwidthfonts/screen.b.l2")  ; 

panel_create_item (panel ,  PANEL_BUTTON, 

PANEL_NOTIFY_PROC,  quit_proc, 

PANEL_LABEL_IMAGE,  panel_button_iitiage  (panel,  "Reset" ,  7, bold)  , 
0); 


It  is  often  usefiil  to  associate  a  menu  with  a  button.  Figure  9-1  illustrates  a  but¬ 
ton  representing  an  online  manual.  The  menu  over  the  button  allows  the  user  to 
bring  up  the  text  for  the  different  chapters: 


Figure  9-1  Associating  a  Menu  With  a  Button 
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To  do  this,  you  must  write  your  own  event  procedure,  as  described  in  Section 
9.13,  Event  Handling.  On  receiving  a  right  mouse  button  down  event,  display 
the  menu  and  take  the  appropriate  action  depending  on  which  menu  item  the  user 
selects.  For  all  other  events,  caU  the  panel’s  default  event  procedure. 

Here  is  the  code  to  create  the  menu  and  the  button,  and  the  event  procedure  to 
display  the  menu: 

static  short  book_array[]  =  { 
tinclude  "book. image” 

}; 

iiipr_static  {book,  64,  64,  1,  book_array>  ; 

Menu  menu  =  menu_create (  MENU_NCOLS,  3,  MENU_STRINGS, 
"Introduction”,  "Pixwins”,  "Cursors”, 

"SunView  Model",  "Text  Subwindows”,  "Icons”, 

"Windows”,  "Panels”,  "Scrollbars", 

"Canvases",  "TTY  Subwindows",  "Selection  Service", 

"Input",  "Menus",  "Motif ier",  0, 

0); 

panel_create_item (panel ,  PANEL_BUTTON , 

PANEL_LABEL_IMAGE,  &book, 

PANEL_EVENT_PROC ,  handle__panel_e  vent , 

0); 

handle_panel_event (item,  event) 

Panel_item  item; 

Event  * event; 

{ 

if  (event_action (event)  == 

MS_RIGHT  &&  event_is_down (event) )  { 

int  chapter  =  menu_show (book_menu,  panel,  event,  0); 
switch  (chapter)  { 

case  1:  /*  Introduction  */  break; 
case  2:  /*  Pixwins  */  break; 


case  15:  /*  Notifier 


*/  break; 


}  else 

panel_default_handle_event (item,  event) ; 
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9.6.  Choices 


Displaying  Choice  Items 


Choice  items  are  the  most  flexible  —  and  complex  —  item  types.^'^  Besides  the 
label,  they  are  composed  of: 

□  a  list  of  either  image  or  string  choices  (specified  via  the  attributes 

PANEL_CHOICE_IMAGES  or  PANEL_CHOICE_STRINGS  ). 

□  a  list  of  mark-images  —  images  to  be  displayed  when  the  corresponding 
choice  is  selected  (  panel_mark_images  ).  The  default  maik  is  a  push¬ 
button  with  the  center  inverted. 

□  a  list  of  nomark-images  —  images  to  be  displayed  when  the  corresponding 
choice  is  not  selected  (  panel_nomark_images  ).  The  default  nomark 
image  is  a  non-inverted  push-button. 

The  choices  are  numbered  beginning  with  zero,  and  there  is  no  restriction  on  the 
number  of  choices  a  single  choice  item  may  have. 

The  attribute  panel_display_level  determines  which  of  an  item’s  choices 
are  actually  displayed  on  the  screen.  The  display  level  may  be  set  to: 

□  PANEL_ALL,  (the  default)  all  choices  are  shown; 

□  PANEL_CURRENT,  only  the  current  choice  is  shown; 

□  PANEL_NONE,  no  choices  are  shown.  Since  the  only  Way  of  selecting  a 
choice  is  through  the  menu,  this  becomes  a  label  with  an  associated  pop  up 
menu. 

If  the  display  level  is  panel_CURRENT  or  PANEL_all,  the  choices  are  placed 
by  default  horizontally  after  the  label.  You  can  lay  them  out  vertically  below  the 
label  by  setting  panel_LAYOUT  to  PANE l_verti CAL.  If  you  want  to  place 
the  choices  or  marks  more  precisely  —  in  order  to  model  a  switch  or  some  other 
special  form  —  you  can  do  so  by  setting  the  appropriate  attribute,  such  as 
PANEL_CHOICE_XS,  PANEL_CHOICE_YS,  PANEL_MARK_XS, 
PANEL_MARK_YS,  etc. 

A  few  words  about  using  the  various  lists  in  choice  items.  The  list  you  give  for 
PANEL_CHOlCE_STRINGS  (or  PANEL_CHOlCE_lMAGES  )  determines  the 
item’s  choices.^^ 


^  For  a  complete  list  of  the  attributes  aj^Hcable  to  choice  items,  see  the  Choice  Item  Attributes  table  in  are 
in  Chapter  19,  SunView  Interface  Summary. 

^  You  must  specify  at  least  one  choice,  so  the  least  you  can  specify  is  a  single  choice  consisting  of  the  null 
string. 
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The  parallel  lists  panel_choice_fonts,  panel_mark_images, 

PANEL_NOMARK_IMAGES,  PANEL_MARK_XS,  PANEL_MARK_YS, 
PANEL_CH0ICE_XS,  and  PANEL_CHOlCE_YS  are  interpreted  with  respect  to 
the  list  of  choices.  For  example,  the  first  font  given  for 
p  ANEL_CHOlCE_FONTS  will  be  used  to  print  the  first  string  given  for 
PANEL_CH0ICE_STRINGS,  the  second  font  will  be  used  for  the  second  string, 
and  so  on. 

The  item  below,  taken  from  iconedit,  shows  how  parallel  lists  can  be  abbrevi¬ 
ated: 


▼ 


r 

panel  create  itein(iced_panel. 

PANEL_CHOICE, 

PANEL  MARK_IMAGES, 

&down__triangle,  0, 

PANEL  NOMARK  IMAGES, 

0, 

PANEL  CHOICE  IMAGES, 

&square_white,  &square_25. 

&square_root ,  &sc[uare_50. 

& square  75,  &square_black,  0, 

PANEL  VALUE, 

2, 

PANEL  CHOICE  XS, 

30,  60,  90,  120,  150,  180, 

0, 

PANEL  MARK  XS, 

34,  64,  94,  124,  154,  184, 

0, 

PANEL_CHOICE_YS , 

345,  0, 

PANEL  MARK  YS, 

363,  0, 

PANEL_NOT IFY_PROC , 

proof  background_proc , 

0); 

_ _ _ _ 

J 

The  item  has  six  choices,  representing  the  six  available  background  patterns  for 
the  proof  area.  Note,  however,  that  three  of  the  lists,  — 
PANEL_MARK_IMAGES,PANEL_CHOICE_YS  and  PANEL_MARK_YS  all 
have  only  one  element.  When  any  of  the  parallel  lists  are  abbreviated  in  this 
way,  the  last  element  given  wiU  be  used  for  the  remainder  of  the  choices.  So,  the 
3 4  5 ,  0  in  the  example  above  serves  as  shorthand  for  345,  345,  345, 

345,  345,  345,0.  All  the  choice  images  will  appear  at  y  coordinate  3  45, 
all  the  maik  images  will  appear  at  y  coordinate  363,  and  all  the  choices  will  have 
down_triangle  as  their  mark  image. 

NOTE  You  can' t  specify  that  a  choice  or  mark-image  appear  atx  =  0  ory  =  0by  using 

the  attributes  panel_CHOICE_xs,  panel_CHOICE_ys, 
PANEL_MARK_XS  or  PANEL_MARK_YS.  Since  these  attributes  take  null- 
terminated  lists  as  values,  the  zero  would  be  interpreted  as  the  terminator  for  the 
list.  You  may  achieve  the  desired  effect  by  setting  the  positions  individually, 
with  the  attributes  PANEL_CHOICE_X,  PANEL_CHOICE_Y, 

PANEL_MARK__X,  or  PANEL_MARK_Y,  which  take  as  values  the  number  of  the 
choice  or  mark,  followed  by  the  desired  position. 
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Choice  Selection 


Choice  Notification 


Choice  Value 


Choice  Menus 


The  user  can  make  a  selection  from  a  choice  item  either  by  selecting  the  desired 
choice  directly,  by  selecting  from  the  associated  menu,  or  by  selecting  the  label, 
which  causes  the  current  choice  to  advance  to  the  next  choice  (or  backup  to  the 
previous  choice  if  the  shift  key  is  pressed  while  selecting); 

Feedback  for  choice  items  comes  in  two  flavors  —  inverted,  in  which  the  current 
choice  is  shown  in  reverse  video,  and  marked,  in  which  the  current  choice  is  indi¬ 
cated  by  the  presence  of  a  distinguishing  mark,  such  as  a  check-maik  or  arrow. 
Specified  the  type  of  feedback  you  want  by  setting  panel_feedback  to  either 
PANEL_INVERTED  orPANEL_MARKED. 

You  may  also  disable  feedback  entirely,  by  setting  panel_FEEDBACK  to 
PANEL_NONE. 

The  default  feedback  is  PANEL_marked,  unless  the  item’s  display  level  is 
current,  in  which  case  the  feedback  is  PANEL_none. 

The  procedure  specified  via  the  attribute  PANEL_notify_proc  will  be  called 
when  the  item  is  selected.  Choice  notify  procedures  are  passed  the  item,  the 
current  value  of  the  item,  and  the  event  which  caused  notification: 

choice_notify_jproc  (item,  value,  event) 

Panel_item  item; 
int  value; 

Event  *event ; 


The  value  passed  to  the  notify  procedure  is  the  ordinal  number  corresponding  to 
the  current  choice  (the  choice  which  the  user  has  just  selected).  The  first  choice 
has  ordinal  number  zero. 

Choice  and  Toggle  items  are  the  only  item  types  for  which  a  menu  appears  by 
default.  To  disable  the  menu  for  a  particular  item,  set  panel_SHOW_menu  for 
that  item  to  FALSE. 

Choice  item  menus  may  be  used  to  represent  either  a  simple  menu  or  a  checklist. 
The  former  is  a  menu  of  commands,  which  gives  no  indication  of  which  com¬ 
mand  was  executed  last;  the  latter  is  a  menu  of  choices  with  a  check-mark  indi¬ 
cating  the  current  choice.  Set  panel_show_menu_mark  to  FALSE  to  obtain 
a  simple  menu,  or  TRUE  to  get  a  checklist. 

NOTE  The  number  of  menu  choices,  if  set  by  PANEL_menu_CHOICE_STRINGS  or 

PANEL_MENU_CHOlCE_lMAGES,  must  be  equal  to  the  number  of  choices  for 
the  item. 
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As  a  basis  for  our  examples  we’ll  take  the  item  in  iconedit  which  allows  the 
user  to  select  the  drawing  mode.  The  item  could  have  been  presented  in  several 
different  forms. 

The  simplest  call  would  specify  the  label  and  choices  as  strings,  and  take  the 
defaults  for  all  other  attributes.  All  the  choices  will  be  displayed,  and  the  feed¬ 
back  will  be  marked,  with  push-buttons  for  the  mark  images: 


Drawing  Node:  ISPoInts  Hllne  QRectangle  Qcircle  Ofext 


panel_create_it.em  (panel ,  PANEL_CHOICE , 

PANEL_LABEL_STRING,  "Drawing  Mode:", 
PANEL_CHOICE_STRINGS,  "Points",  "Line",  "Rectangle", 

"Circle",  "Text",  0, 


0); 


You  can  specify  a  custom  mark,  such  as  this  small  pointer,  to  indicate  the  current 
choice: 


Drawing  Hode:  Points  ►Line  Rectangle  Circle  Text 


static  short  pointer_array [ ]  =  { 

♦include  "pointer. pr" 

}; 

mpr_static (pointer,  16, 

16,  1,  pointer_array) ; 

panel  create  item (panel. 

PANEL_CHOICE, 

P ANEL_LABEL_STRI NG , 

"Drawing  Mode:", 

PANEL  MARK_IMAGES, 

Spointer,  0, 

PANEL  NOMARK  IMAGES, 

0, 

PANEL  CHOICE  STRINGS,  "Points",  "Line",  "Rectangle", 

"Circle",  "Text",  0, 

0); 

1 

J 

Setting  PANEL_FEEDBACK  to  PANEL_INVERTED  produces: 

Drawing  Mode:  Points  lil'iTil  Rectangle  Circle  Text 
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Often  space  on  the  panel  is  limited,  and  it  is  appropriate  to  save  space  by  only 
showing  the  currently  selected  choice.  You  can  do  that  by  disabling  feedback 
and  displaying  only  the  current  choice: 

Drauing  Mode:  Line 


panel^create  item (panel , 

PANEL_CHOICE, 

\ 

PANEL_LABEL_STRING, 

"Drawing  Mode:", 

PANEL_CHOICE_STRINGS , 

"Points",  "Line",  "Rectangle", 
"Circle",  "Text",  0, 

PANEL_DI SPLAY_LEVEL , 

PANEL  CURRENT, 

PANEL  FEEDBACK, 

0); 

PANEL_NONE, 

V _ 

Such  an  item  has  the  drawback  of  looking  to  the  user  like  a  text  item.  One  solu¬ 
tion  to  this  problem  is  to  provide  a  distinguishing  mark  which  clearly  indicates 
the  item’s  type,  as  in: 

Drauing  Mode:  Ollne 


The  double-arrow  image  suggests  a  cycling  motion,  indicating  to  the  user  that  the 
item  is  a  choice  item  with  more  choices  available.  To  get  the  cycle  image,  use 
the  special  item  type  PANEL_CYCLE:^^ 


panel_create_item (panel , 

PANEL_CYCLE, 

- V 

PANEL_LABEL_STRING, 

"Drawing  Mode : " , 

PANEL_CHOICE_STRINGS , 

"Points",  "Line",  "Rectangle", 
"Circle",  "Text",  0, 

0); 

V _ 

J 

^  Note  that  a  tycle  item  is  simply  a  choice  item  with  some  attributes  initialized  —  the  display  level  is  set  to 
current  and  the  on -mark  is  set  to  the  <ycle  image.  Once  created,  cycle  items  behave  in  exactly  the  same  way  as 
choice  items. 
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With  some  effort,  you  can  use  a  choice  item  to  model  a  dial,  as  in  Figure  9-2. 


Figure  9-2  A  Dial-Like  Choice  Item 


Rect 


Line 

Points 


Circle 

Text 


Drawing  Mode 


The  way  to  make  a  such  a  dial  is  to  make  an  image  for  each  dial  setting,  and  use 
these  images  as  the  on-marks.  Place  the  on-marks  and  the  choices  explicitly  — 
the  on-marks  in  the  center,  forming  the  dial,  and  the  choices  around  the  dial’s 
perimeter: 


r 

panel_create_item (panel , 

PANEL_CHOICE, 

PANEL_CHOICE_STRINGS, 

"Points",  "Line",  "Rect", 

"Circle",  "Text",  0, 

PANEL  MARK  IMAGES, 

&dial  1,  &dial  2,  Sdial  3, 

&dial_4,  &dial_5,  0, 

PANEL  NOMARK_IMAGES , 

0, 

PANEL  CHOICE  XS, 

7,  34,  82,  133,  145,  0, 

PANEL_CHOICE_YS , 

53,  33,  20,  33,  53,  0, 

PANEL_MARK_XS, 

66,  0, 

PANEL_MARK_YS, 

o 

o 

PANEL_LABEL_STRING, 

"Drawing  Mode", 

PANEL  LABEL  X, 

30, 

PANEL_LABEL_Y, 

PANEL  LABEL  FONT, 

65, 

pf  open (”/usr/lib/fonts/fixedwidthfonts/gallant . r . 19") , 
0); 

L _ 

. . .  J 

The  form  which  is  actually  used  in  shown! coneditis  Figure  9-3.  It  employs 
vertical  layout,  images  for  the  choices,  and  strings  for  the  menu; 

Figure  9-3  iconedit  ’s  Drawing  Mode  Choice  Item 
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9.7.  Toggles 


Displaying  Toggles 


Toggle  Selection 


Toggle  Notification 


Toggle  Value 


- —  > 

panel_creat.e_it.em  (panel ,  PANEL_CHOICE , 

PANEL_LAYOUT,  PANEL_VERTICAL, 

PANEL_CHOICE_IMAGES,  fipoints,  &line,  ^rectangle, 

Scircle,  Stext,  0, 

PANEL_MENO_CHOICE_STRINGS,  "Points”,  "Line",  "Rectangle", 

"Circle",  "Text",  0, 

PANEL_MARK_IMAGES,  &drawing_hand,  0, 

PANEL_NOMARK_IMAGES,  0, 

0); 

_ _ _ 


Toggle  items  are  identical  in  structure  to  choice  items  —  they  have  a  label  and 
parallel  lists  of  choices,  on-marks  and  off-maiks.  They  differ  from  choice  items 
in  certain  aspects  of  their  display  options,  their  selection  behavior  and  the 
interpretation  of  their  value.  These  differences  are  highlighted  below. 

Toggle  items  may  have  a  PANEL__DISPLAY_LEVEL  of  either  panel_ALL  — 
all  choices  visible,  or  panel_NONE  —  no  choices  visible.  The  default  is 
PANEL_ALL. 

Since  there  is  no  notion  of  the  current  choice  for  a  toggle  item,  a  display  level  of 
PANEL_CURRENT  is  not  aUowed. 

Toggle  items,  like  choice  items,  may  have  either  inverted  or  marked  feedback, 
depending  on  the  value  of  PANEL_FEEDBACK.  The  default  is 
PANEL_MARKED.  For  inverted  feedback,  specify  panel_inverted. 
PANEL_N0NE  is  not  aUowed. 

Toggle  items  may  be  selected  by  clicking  on  the  desired  choice  or  through  the 
menu.  Selecting  a  choice  causes  that  choice  to  toggle  on  or  off  (change  state); 
other  choices  are  not  affected. 

If  there  is  only  one  choice,  it  may  be  toggled  by  selecting  the  label;  if  there  is 
more  than  one  choice,  selecting  the  label  has  no  effect 

The  parameters  for  the  notify  procedure  are  the  same  as  for  choice  items  except 
that  the  value  passed  is  a  bit  mask  instead  of  an  integer: 

toggle_notify_proc (item,  value,  event) 

Panel_item  item; 
unsigned  int  value; 

Event  *event ; 


The  value  passed  to  the  notify  procedure  is  a  bit  mask  representing  the  state  of 
the  first  32  choices  —  if  a  bit  is  one,  then  the  corresponding  choice  is  on,  if  a  bit 
is  zero,  then  the  corresponding  choice  is  off.  (The  least  significant  bit  is  bit  zero, 
which  maps  to  choice  zero.) 
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Example 


Figure  9-4  illustrates  an  item  which  lets  you  set  the  -/,  -r,  or  -a  flags  for  the  Is 
command: 

Figure  9-4  A  Toggle  Item 

Format  Options: 

Long 

□  Reverse 
1^ Shou  all  files 


( 

format_item  =  panel_create_item (panel,  P ANEL_TOGGLE , 

PANEL_LABEL_STRING, 

"Format  Options : " , 

PANEL_LAYOUT, 

PANEL_VERTICAL, 

PANEL_CHOICE_STRINGS , 

"Long" , 

"Reverse" , 

"Show  all  files", 
n 

P ANEL_TOGGLE_VALUE , 

0,  TRUE, 

P ANEL_TOGGLE_VALUE , 

2,  TRUE, 

P ANEL_NOT IF Y_PROC , 

format_notify_proc. 

0); 

_ 

J 

You  can  get  or  set  the  value  of  a  particular  choice  —  including  choices  beyond 
the  first  32  —  with  PANEL_TOGGLE_VALUE.  When  used  to  set  the  value,  this 
attribute  takes  two  values:  the  index  of  the  choice  to  set,  and  the  desired  value. 

In  the  above  example,  PANEL_T0GGLE__VALUE  is  used  to  initialize  the  first  and 

third  choices  to  TRUE.  To  find  out  the  value  of  the  third  choice,  you  would  caU: 

- - 

value  =  (int)  panel_get (format_item,  PANEL_TOGGLE_VALOE ,  2)  ; 

^ 


You  can  also  use  the  attribute  PANEL_VALUE  to  set  and  get  the  state  of  a 
toggle’s  choices.  As  mentioned  on  the  previous  page,  a  toggle’s  value  is  a  bit 
mask  representing  the  state  of  the  first  32  choices.  To  facilitate  working  with  the 
value,  you  might  first  define  names  corresponding  to  each  choices,  and  a  macro 
to  test  for  the  corresponding  bit  in  the  value,  like  this: 


#define 

LONG 

0 

♦define 

REVERSE 

1 

♦define 

SHOW_ALL 

2 

♦define 

toggle_bit 

_on (value,  bit) 

((value)  &  (1  «  (bit))) 

_ 

7 

You  can  then  use  the  value  in  the  notify  procedure,  as  in: 


microsystems 


Revision  A,  of  May  9, 1988 


178  SunView  1  Programmer’s  Guide 


Toggle  Menus 


9.8.  Text 

Displaying  Text  Items 


- ^ 

format_notify_j3roc  (format_item,  value,  everit) 

Panel_item  fonnat_item; 
unsigned  int  value; 

Event  *event; 

{  ■ 

if  (toggle_bit_on (value,  LONG) )  { 

} 

if  (toggle_bit_on (value,  REVERSE) )  { 

} 

if  (toggle_bit_on (value,  SHOW_ALL) )  { 

} 

} 

_ ^ - > 


'w' 


Or  you  can  retrieve  the  value  outside  of  the  notify  procedure,  as  in: 


unsigned  value; 

value  =  panel_get_value (f ormat_item)  ; 

if  (toggle_bit_on (value,  LONG))  { 

} 

> - — 

j 

'  1 
\  7 

The  menu  has  as  many  lines  as  choices,  and  each  line  toggles  when  selected.  In 
other  words,  the  mark  indicating  “on”  (PANEL_MENU__MARK_IMAGE)  is  alter¬ 
nated  with  the  mark  signifying  “off’  (panel_MENU_NOMARK_IMAGE)  each 
time  the  user  selects  a  given  line. 

To  disable  the  menu,  set  panel  show_menu  to  false. 


The  value  component  of  a  text  item  is  the  string  which  the  user  enters  and  edits. 
It  is  drawn  on  the  screen  just  after  the  label,  as  in: 

Name:  Eduard  G.  Robinson 


- - — - - -  ^ 

panel_create_item (panel,  PANEL_TEXT, 

PANEL_LABEL_STRING,  "Name:", 

PANEL_VALUE,  "Edward  G.  Robinson", 

0)  ; 


If  PANEL_LAYOUT  is  set  to  PANEL_VERTICAL,  overriding  the  default  of 
PANEL_HORl  ZONTAL,  the  value  will  be  placed  below  the  label. 

The  number  of  characters  of  the  text  item’s  value  which  are  displayable  on  the 
screen  is  set  via  PANEL_VALUE_DISPLAY_LENGTH,  which  defaults  to  80 
characters.  When  characters  are  entered  beyond  this  length,  die  value  string  is 
scrolled  one  character  to  the  left,  so  that  the  most  recently  entered  character  is 
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Text  Selection 


always  visible.  As  the  string  scrolls  to  the  left,  the  leftmost  characters  move  out 
of  the  visible  display  area.  The  presence  of  these  temporarily  hidden  characters 
is  indicated  by  a  small  left-pointing  triangle.  So  setting  the  display  length  to  12 
in  the  above  caU  would  produce: 

Name:  <G.  Robinson 

As  excess  characters  are  deleted,  the  string  is  scrolled  back  to  the  right,  imtil  the 
actual  length  becomes  equal  to  the  displayed  length,  and  the  entire  string  is  visi¬ 
ble. 

It  is  sometimes  desirable  to  have  a  protected  field  where  the  user  can  enter 
confidential  information.  The  attribute  panel_mask_CHAR  is  provided  for 
this  purpose.  When  the  user  enters  a  character,  the  character  you  have  specified 
as  the  value  of  panel_mask_char  wiU  be  displayed  in  place  of  the  character 
the  user  has  typed.  So  setting  panel_mask_CHAR  to  ”  would  produce: 

Passuord: 

If  you  want  to  disable  character  echo  entirely,  so  that  the  caret  does  not  advance 
and  it  is  impossible  to  teU  how  many  characters  have  been  entered,  use  the  space 
character  as  the  mask.  You  can  remove  the  mask  and  display  the  actual  value 
string  at  any  time  by  setting  the  mask  to  the  null  character. 

The  maximum  number  of  characters  which  can  be  typed  into  a  text  item 
(independently  of  how  many  are  displayable)  is  set  via  the  attribute 
PANEL_VALUE_STORED_LENGTH.  Attempting  to  enter  a  character  beyond 
this  limit  causes  the  field  to  overflow,  and  the  character  is  lost.  The  value  string 
is  blinked  to  indicate  to  the  user  that  the  text  item  is  not  accepting  any  more  char¬ 
acters. 

The  stored  length,  like  the  displayed  length,  defaults  to  80  characters. 


A  panel  may  have  several  text  items,  exactly  one  of  which  is  current  at  any  given 
time.  The  current  text  item  is  the  one  to  which  keyboard  input  is  directed,  and  is 
indicated  by  a  caret  at  the  end  of  the  item’s  value.  (If  PANEL_blink_CARET 
is  TRUE,  the  caret  will  blink  as  long  as  the  cursor  is  in  the  panel.)  Selection  of  a 
text  item  (i.e.  pressing  and  releasing  the  left  mouse  button  anywhere  within  the 
item’s  rectangle)  causes  that  item  to  become  current.  A  text  item  also  becomes 
current  if  it  is  displayed  after  being  hidden  —  i.e.  if  PANEL_SHOW_lTEM  is  set 
to  TRUE. 

You  can  find  out  which  text  item  has  the  caret,  or  give  the  caret  to  a  specified  text 
item,  by  means  of  the  panel  attribute  panel_CARET_ITEM.  The  c^ 

window_set (panel,  PANEL_CARET_ITEM,  name_item,  0); 
s _ ! _ > 


moves  the  caret  to  name  item,  while 
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(Panel_item) window_get (panel ,  PANEL_CARET_ITEM) ; 

^ _ / 


retrieves  the  item  with  the  caret. 

You  can  rotate  the  caret  through  the  text  items  with  the  following  two  routines: 

panel_advance_caret (panel) 

Panel  panel; 

panel_backup_caret (panel) 

Panel  panel; 

Advancing  past  the  last  text  item  places  the  caret  at  the  first  text  item;  backing  up 
past  the  first  text  item  places  the  caret  at  the  last  text  item. 

The  notification  behavior  of  text  items  is  rather  more  complex  than  that  of  the 
other  item  types.  You  can  control  whether  your  notify  procedure  is  called  on 
each  input  character  or  only  on  selected  characters.  If  your  notify  procedure  is 
called,  then  the  value  it  returns  teUs  the  panel  package  what  to  do  —  whether  to 
insert  the  character,  advance  to  the  next  text  item,  etc. 

When  your  notify  procedure  will  be  called  is  determined  by  the  value  of 
PANEL_NOTiFY_LEVEL.  Possible  values  are  given  in  the  following  table. 

Table  9-1  Text  Item  Notification 


Notification  Level 

Causes  Notify  Procedure  to  be  Called 

PANEL  NONE 

Never 

PANEL_NON_PRINTABLE 

On  each  non-printable  input  character 

PANEL_SPECIFIED 

If  the  input  char  is  found  in  the  string 

given  for  the  attribute 

PANEL  NOTIFY  STRING 

PANEL_ALL 

On  each  input  character 

PANEL_NOTIFY_LEVEL  defaults  tO  PANEL_SPECIFIED,  and 
PANEL_N0TIFY_STRING  defaults  to  \n\r \t  (i.e.,  notification  on  line-feed,  ^ 
carriage-return  and  tab). 

What  happens  when  the  user  types  a  character?  The  panel  package  treats  some 
characters  specially.  I  Meta-C  I  Meta-^  I.  and  I  Meta-X  I  are  mapped  to  the  Sun- 
View  functions  1  Copy  1. 1  Paste  1.  and  ( Cut  I.  respectively.  When  the  user  types 
these  characters,  the  panel  package  notices  them  and  performs  the  appropriate 
operation,  without  passing  them  on  to  your  notify  procedure. 

The  user’s  editing  characters  —  erase,  erase-word  and  kill  —  are  also  treated 
specially.  If  you  have  asked  for  the  character  by  including  it  in 
PANEL_N0TIFY_STRING,  the  panel  package  will  call  your  notify  procedure. 


The  Meta  key  is  [  Left  1  or  ( Right  I  on  the  Sun-2  and  Sun-3  keyboards.  On  the  type  4  keyboard,  the  f  Meta ) 
keys  are  marked  with  diamonds  [  ♦  I 
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After  the  notify  procedure  returns,  the  appropriate  editing  operation  will  be 
applied  to  the  v^ue  string.  (Note:  the  editing  characters  are  never  appended  to 
the  value  string,  regardless  of  the  return  value  of  the  notify  procedure.) 

Characters  other  than  the  special  characters  described  above  are  treated  as  fol¬ 
lows.  If  your  notify  procedure  is  not  called,  then  the  character,  if  it  is  printable, 
is  appended  to  the  value  string.  If  it  is  not  printable,  it  is  ignored.  If  your  notify 
procedure  is  called,  what  happens  to  the  value  string,  and  whether  the  caret 
moves  to  another  text  item,  is  determined  by  the  notify  procedure’s  return  value. 
The  following  table  shows  the  possible  return  values: 

Table  9-2  Return  Values  for  Text  Item  Notify  Procedures 


Value  Returned 

Action  Caused 

PANEL_INSERT 

Character  is  appended  to  item’s  value 

PANEL  NEXT 

Caret  moves  to  next  text  item 

PANEL  PREVIOUS 

Caret  moves  to  previous  text  item 

PANEL_NONE 

Ignore  the  input  character 

If  a  non-printable  character  is  inserted,  it  is  appended  to  the  value  string,  but 
nothing  is  shown  on  the  screen. 


If  you  don’t  specify  your  own  notify  procedure,  the  default  procedure 
panel_text_notif  y  ( )  will  be  called  at  the  appropriate  time,  as  determined 
by  the  setting  of  panel_notify_level.  The  procedure  is  shown  below: 

Panel_setting 

panel_text_notify (item,  event) 

Panel_item  item 
Event  *event 

This  procedure  returns  a  panel  setting  enumeration  which  causes:  1)  the  caret  to 
move  to  the  next  text  item  on  f  RETURN^l  or  f  TAB  ]:  2)  the  caret  to  move  to  the 
previous  text  item  on  I  SHIFT  1 1  RETURN  I  or  I  i  1  TABTI  3)  printable  char¬ 
acters  to  be  inserted;  and  4)  aU  other  characters  to  be  discarded. 


Writing  Your  Own  Notify 
Procedure 


By  writing  your  own  notify  procedure,  you  can  tailor  the  notification  behavior  of 
a  given  text  item  to  support  a  variety  of  interface  styles.  On  one  extreme,  you 
may  want  to  process  each  character  as  the  user  types  it  in.  For  a  different  appli¬ 
cation  you  may  not  care  about  the  characters  as  they  are  typed  in,  and  only  want 
to  look  at  the  value  string  in  response  to  some  other  button.  A  typical  example  is 
getting  the  value  of  a  filename  field  when  the  user  presses  the  Load  button. 

Text  item  notify  procedures  are  passed  the  item  and  the  event  which  caused 
notification: 

Panel_setting 

text_notify_proc (item,  event) 

Panel_item  item; 

Event  *event ; 

The  input  character  is  referenced  by  event_act  ion  ( event ) . 
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For  example,  suppose  you  want  to  be  notified  only  when  the  user  types  fEscI  or 
[  Control-C  1  into  an  item,  but  you  still  want  them  to  be  able  to  move  to  the  next 
item,  tab,  or  select  i  Return,  i  Create  the  item  as  shown  below. 


name_item  =  panel_create_item  (panel ,  PANEL_TEXT, 

PANEL_LABEL_STRING, 

"Enter  Name  Here:", 

PANEL  NOTIFY  LEVEL, 

PANEL  SPECIFIED, 

PANEL_NOTIF Y_STRI NG , 

"\n\r\t\033\03". 

PANEL_NOTIFY  PROG, 

0) ; 

name_proc , 

_ 

J 

Note  that  you  must  remember  to  return  the  appropriate  value  from  your  notify 
procedure.  The  easiest  way  to  do  this  is  to  simply  call  the  default  text  notify  pro¬ 
cedure,  and  return  what  it  returns: 


Panel_setting 
name_j3roc  (item,  event) 

Panel_item  item; 

Event  *event; 

{ 

switch  (event_action (event ) )  { 

case  '  33' :  /*  user  pressed  [Esc]  */ 

/*  special  processing  of  escape  *1 
return  (PANEL_NONE) ; 

case  '  03' :  /*  user  pressed  [Ctrl-C]  */ 

/*  special  processing  of’C  */ 
return  ( PANEL_NONE  > ; 


default : 
return 

} 

} 


(panel_text_notify (item. 


event) ) ; 


Text  Value  As  shown  in  the  example  under  Displaying  Text  Items,  you  can  set  the  value  of  a 

text  item  at  any  time  via  PANEL_value.  You  can  also  use  the 
panel_set_value  { )  macro,  as  in: 

panel_set_value (name_item,  "Millard  Fillmore"); 

< _ > 


The  following  call  retrieves  the  value  of  name_item  into  name: 


Panel_item  name_item; 

char  name[NAME_ITEM_MAX_LENGTH] ; 

strcpy(name,  (char  *) panel  get  value (name  item)); 

V, 

J 

Note  that  name_item  should  have  been  created  with  a 

PANEL_VALUE_STORED_LENGTH  not  greater  than 

NAME  ITEM  MAX  LENGTH,  SO  the  buffer  name  wiU  not  overflow. 
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Example 


A  menu  may  be  associated  with  a  text  item  by  setting  panel_show_menu  to 

TRUE. 

One  use  of  text  item  menus  is  to  make  any  item-specific  “accelerators”,  or  char¬ 
acters  which  cause  special  behavior,  visible  to  the  user.  This  usage  of  accelera¬ 
tors  may  be  seen  in  Figure  9-5  which  is  taken  from  iconedit .  The  item 
labelled  File:  holds  the  name  of  the  file  being  edited.  In  addition  to  typing  print¬ 
able  characters,  which  are  appended  to  the  value  of  the  item,  the  user  can  type 
(Esc  I  for  filename  completion,  ( Cnntrnl-L  I  to  load  an  image  from  the  file, 

( Cnntrol-S  I  to  Store  an  image  to  the  file,  or  ( Control-B  ]  to  browse  the  images  in  a 
directory. 

Figure  9-5  A  Text  Menu 


File:  dervish. image 


ESC  -  Filename  completion 


-  Load  image  from  file 


- 

- 

-«Q  - 


Store  image  to  file 
Brouse  directory 
Quit 


♦define  ESC  27 
♦define  CTRL_L  12 
♦define  CTRL_S  19 
♦define  CTRL_Q  17 
♦define  CTRL_B  2 


filename_item  =  panel_create_item (panel,  PANEL_TEXT, 


PANEL_LABEL_STRING, 

P ANEL_NOT I F Y_LEVEL , 

P ANEL_NOT IF  Y_PROC , 

P ANEL_VALUE_D I SP  LAY_LENGTH , 
P ANEL_SHOW_MEND , 

PANEL  MENU  CHOICE  STRINGS, 


PANEL_MENU_CHOICE_VALOES , 
0); 


"File:”, 

PANEL_ALL, 
f  ilenaine_proc , 

18, 

TRUE, 

ESC  -  Filename  con^letion”, 
"L  -  Load  image  from  file”, 
"S  -  Store  image  to  file", 
"B  -  Browse  Directory", 

"Q  -  Quit", 

0, 

ESC, CTRL_L, CTRL_S, 

CTRL  B,CTRL  Q,  0, 


The  last  two  attributes  specify  the  menu.  PANEL_jyiENU_CHOlCE_STRlNGS  is 
a  nuU-terminated  array  of  strings  to  appear  as  the  selectable  lines  of  the  menu. 
The  value  that  the  menu  returns  for  each  of  its  lines  is  specified  via 
PANEL_MENU_CHOlCE__VALUES.  So  if  the  menu  line  ‘"L  -  Load  image  from 
file’  is  selected,  the  menu  will  return  the  value  CTRL_l.  The  value  returned  by 
the  menu  is  passed  directly  to  the  text  item,  just  as  if  it  had  been  typed  at  the  key¬ 
board. 
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9.9.  Sliders 
Displaying  Sliders 


Slider  Selection 

Slider  Notification 


A  slider  has  four  displayable  components:  the  label,  the  current  value,  the  slider 
bar,  and  the  minimum  and  maximum  allowable  integral  values  (the  range). 

When  PANEL_SHOW_VALUE  is  TRUE,  the  current  value  is  shown  in  brackets 
after  the  label.  The  font  used  to  render  the  value  is  panel_value_font  . 

The  slider  bar  width  in  pixels  is  set  with  PANEL_SLIDER_WIDTH.^^  The 
minimum  and  maximum  allowable  values  are  set  with  PANEL_MIN_VALUE 
and  PANEL_MAX_VALUE.  The  width  of  the  slider  bar  corresponding  to  the 
current  value  is  filled  with  grey.  The  slider  bar  is  always  displayed,  unless  the 
item  is  hidden  (i.e.,  PANEL_SHOW_item  is  false).  When 
PANEL_SHOW_RANGE  is  TRUE,  the  minimum  value  of  the  slider 
(P  ANEL_MIN_VALUE)  is  shown  to  the  left  of  the  slider  bar  and  the  maximum 
value  (PANEL_MAX_VALUE)  is  shown  to  the  right  of  the  slider  bar. 

Only  the  slider  bar  of  a  slider  may  be  selected.  When  the  left  mouse  button  is 
pressed  within  the  slider  bar  or  the  mouse  is  dragged  into  the  slider  bar  with  the 
left  mouse  button  pressed,  the  grey  shaded  area  of  the  bar  will  advance  or  retreat 
to  the  position  of  Ae  cursor.  If  the  mouse  is  dragged  left  or  right  within  the 
slider  bar,  the  grey  area  will  be  updated  appropriately.  If  the  cursor  is  dragged 
outside  of  the  slider  bar,  the  original  value  of  the  slider  (i.e.,  the  value  before  the 
left  button  was  pressed)  will  be  restored. 

Slider  notify  procedures  are  passed  the  item,  the  item’s  value  at  time  of 
notification,  and  the  event  which  caused  notification: 

slider_notify_proc (item,  value,  event) 

Panel_item  item; 
int  value; 

Event  *event ; 

The  notification  behavior  of  a  slider  is  controlled  by  PANEL_NOTIFY_LEVEL. 
When  PANEL_NOTlFY_LEVEL  is  Set  to  PANEL_DONE,  the  notify  procedure 
will  be  called  only  when  the  select  button  is  released  within  the  slider  bar.  When 
PANEL_NOTlFY_LEVEL  is  set  to  PANEL_ALL,  the  notify  procedure  will  be 
called  whenever  the  value  of  the  slider  is  changed.  This  includes: 

□  when  the  select  button  is  first  pressed  within  or  dragged  into  the  slider  bar, 

□  each  time  the  mouse  is  dragged  within  the  slider  bar, 

□  when  the  mouse  is  dragged  outside  the  slider  bar, 

□  when  the  select  button  is  released. 


®  If  you  want  to  ^dfy  tte  width  in  characters,  use  the  “colunui  units”  macro  ATTR_COLS  ( )  described  in 
Chapter  IS,  Attribute  Utilities. 
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Slider  Value  The  value  of  a  slider  is  an  integer  in  the  range  panel_min_VALUE  to 

PANEL_MAX_VALUE.  You  can  retrieve  or  ^t  a  slider’s  value  with  the  attribute 
PANEL_VALUE. 

Example  Figure  9-6  illustrates  a  typical  slider,  which  might  be  used  to  control  the  bright¬ 

ness  of  a  screen: 

Figure  9-6  A  Typical  Slider 


Brightness:  [75] 


f 

- >1 

panel  create  item (panel,  PANEL_SLIDER 

r 

PANEL_LABEL_STRING, 

"Brightness:  ", 

PANEL  VALUE, 

75, 

PANEL_MI N_VALaE , 

0, 

PANEL  MAX  VALUE, 

100, 

P ANEL_SLIDER_WI DTK , 

300, 

PANEL_NOTIFY_PROC , 

brightne s s_proc , 

o>; 

1 

J 

9.10.  Painting  Panels  and 
Individual  Items 


To  repaint  either  an  individual  item  or  an  entire  panel,  use: 

panel_paint (panel_object ,  paint_behavior) 
<Panel_item  or  Panel>  panel_ob ject ; 
Panel_setting  paint_behavior; 


paint_behavior  should  be  either  PANEL_CLEAR,  which  causes  the  rectan¬ 
gle  occupied  by  the  panel  or  item  to  be  cleared  prior  to  repainting,  or 
PANE  L_NO_C  LEAR,  which  causes  repainting  to  be  done  without  any  prior  clear¬ 
ing. 

You  don’t  have  to  call  panel_j5aint  ( )  for  items  which  you  create  at  the  same 
time  as  you  create  the  panel  —  when  the  panel  is  initially  displayed,  each  of  its 
items  will  be  painted.  Note,  however,  that  simply  creating  a  panel  item  does  not 
cause  it  to  be  painted.  So  items  which  you  create  ctfter  the  panel  has  been  ini¬ 
tially  displayed  wiU  not  appear  until  you  call  panel_paint  ( ) . 

The  special  attribute  PANEL_PAINT  is  provided  to  allow  you  to  control  the 
“repaint  behavior”  of  an  item  when  one  of  its  attributes  is  set.  PANEL_PAINT 
has  three  possible  values: 

□  PANEL_CLEAR  —  the  item  wiU  be  automatically  cleared  and  repainted 
after  each  call  to  panel_set  ( ) . 

□  PANEL_NO_CLEAR  —  the  item  will  be  automatically  repainted  (without 
any  prior  clearing)  after  each  panel_set  ( )  caU. 

□  PANEL_NONE  —  no  automatic  repainting  will  be  done. 

The  default  value  for  panel_paint  is  panel_clear.  Thus,  in  the  default 
case,  you  do  not  need  to  call  panel_paint  ( )  after  calling  panel_set  { ) . 
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You  can  set  the  repaint  behavior  for  an  item  when  the  item  is  created,  or  for  all 
items  in  the  panel  when  the  panel  is  created.  The  item’s  repaint  behavior  may 
not  be  reset  after  the  item  is  created.  However,  you  may  temporarily  override  an 
item’s  repaint  behavior  on  any  call  to  panel_set  ( )  by  giving  a  different  set¬ 
ting  for  PANEL_PAINT.  The  examples  which  foUow  show  two  possible  repaint 
policies. 


Example  1: 


- - 

iteml  =  panel_create_item (panel,  PANEL_TEXT, 

PANEL_LABEL_STRING,  "Enter  Name:”, 

PANEL_VALUE_DISPLAY_LENGTH,  10, 

PANEL_PAINT,  PANEL_NONE, 

0); 

(begin processing  events,  etc...) 

pane l_set (iteml,  PANEL_ITEM_X,  10,  PANEL_ITEM_Y,  50,  0); 
pane l_set  (iteml,  PANEL_LABEL_IMAGE,  Spixrectl,  0); 
panel_set (iteml,  PANEL_VALUE_DISPLAY_LENGTH,  30,  0); 
panel_paint  (iteml,  PANEL_CIiEAR) ; 

< _ > 
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Example  2: 


- - - - 

item2  =  panel_creat.e_item (panel,  PANEL_TEXT, 

PANEL_LABEL_STRING,  "Enter  Name: " , 

P ANEL_VALUE_D I SPLAY_LENGTH ,  10, 

0); 

(begin processing  events,  etc...) 

panel_set (item2, 

PANEL_ITEM_X ,10, 

PANEL_ITEM_Y,  50, 

PANEL_PAINT,  PANEL_NONE, 

0); 

panel_set (item2, 

PANEL_LABEL_I MAGE ,  &  pixr ect 1 , 

PANEL_PAINT,  PANEL_NONE, 

0-); 

panel_set (item2, 

PANEL_VALUE_DISPIiAY_LENGTH,  30, 


The  above  two  examples  each  produce  the  same  effect.  In  the  first  example,  the 
item’s  repaint  behavior  is  set  to  PANEL_NONE  at  creation  time,  so  it  is  not 
repainted  automatically  after  the  panel_set  { )  calls,  and  no  repainting  occurs 
until  the  call  to  panel_j>aint  ( ) .  In  the  second  example,  the  item’s  repaint 
behavior  is  the  default,  panel_CLEAR.  This  is  overridden  in  the  first  two 
panel_set  ( )  calls,  so  no  repainting  occurs.  However,  it  is  not  overridden  in 
the  third  caU  to  panel_set  () ,  so  repainting  occurs  before  that  call  returns. 

As  mentioned  above,  the  repaint  behavior  for  all  items  in  a  panel  can  be  set  when 
the  panel  is  created,  e.g.: 

- - - — - - , 

window_create (frame,  PANEL,  PANEL_PAINT,  PANEL_NONE,  0) ; 

- > 

AU  items  created  in  the  above  panel  will  have  a  repaint  behavior  of 
PANEL  NONE. 
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9.11.  Iterating  Over  a  You  can  iterate  over  each  item  in  a  panel  with  the  two  attributes  \ _ J 

Panel’s  Items  panel_first_item  and  panel_next_item.  A  pair  of  macros, 

panel_each_item  ( )  and  panel_end_each  are  also  provided  for  this 
purpose.  For  example,  to  destroy  each  item  in  a  panel  you  would  call: 

- \ 

Panel_item/  item; 

panel_each_item (browser,  item) 
panel_destroy_item(item) ; 
panel_end_each 

\ _ _ _ > 


NOTE  Parentheses  are  not  required  around  the  statements  to  be  executed  on  each  itera¬ 
tion.  Also,  a  semicolon  is  not  required  after  panel_end._each. 

9.12.  Panel  Item  Client  One  attribute  applicable  to  items  of  all  types  which  should  be  mentioned  is 

Data  panel_client_data.  You  can  use  this  attribute  in  a  variety  of  ways. 

Perhaps  the  most  common  use  is  to  associate  a  unique  identifier  with  each  item. 
This  is  convenient  in  the  case  where  you  have  many  items,  or  where  you  are 
creating  and  destroying  items  dynamically.  If  you  need  to  pick  one  item  out  of 
all  the  items,  you  can  store  an  identifier  (or  a  class)  with  it  via 
panel_CLIENT_DATA,  and  then  query  the  item  directly  to  find  out  its 
identifier  or  class. 

The  detool  program  in  Appendix  A,  Example  Programs,  demonstrates  this  use  of 
PANEL_CLIENT_DATA.  The  panel  buttons  for  its  number  keys  0-9  share  the 
same  notify  procedure.  Each  button’s  PANEL_CLIENT_DATA  holds  the  ASCn 
digit  displayed  on  the  button;  when  a  button  is  pushed,  the 
PANEL_CLIENT_DATA  is  retrieved  and  displayed  on  the  “screen”  of  the  calcu¬ 
lator.  This  saves  having  a  different  notify  procedure  for  every  button. 

You  can  also  use  PANEL_CLIENT_data  to  associate  a  pointer  to  a  private 
stmeture  with  an  item.  For  one  example  of  this  usage,  see  the  example  in  the 
next  section  under  Writing  Your  Own  Event  Handler.  Another  application  would 
be  to  link  several  items  together  into  a  list  which  is  completely  under  your  con¬ 
trol.  V 
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9.13.  Event  Handling  This  section  describes  how  the  panel  package  handles  events.^^  If  you  require  a 

behavior  not  provided  by  default,  you  can  write  your  own  event  handling  pro¬ 
cedure  for  either  an  individual  item  or  the  panel  as  a  whole. 

Default  Event  Handling  Using  the  default  event  handling  mechanism,  events  are  handled  for  all  the  panel 

items  in  a  uniform  way.  A  single  routine  reads  the  events,  updates  an  internal 
state  machine,  and  maps  the  event  to  an  action  to  be  taken  by  the  item.  Actions 
fall  into  two  categories:  previewing  and  accepting.  The  previewing  action  gives 
the  user  visual  feedback  indicating  what  will  happen  when  he  releases  the  mouse 
button.  The  accepting  action  causes  the  item’s  value  to  be  changed  and/or  its 
notify  procedure  to  be  called,  with  the  event  passed  as  the  last  argument. 


The  default  event-to-action  mapping  is  given  in  the  following  table: 


Event 

Action 

Left  button  down  or  drag  in  w/left  button  down 

Begin  previewing 

Drag  with  left  button  down 

Update  previewing 

Drag  out  of  item  rectangle  with  left  button  down 

Cancel  preview 

Left  button  up 

Accept 

Right  button  down 

Display  menu  &  accept  user’s  selection 

Keystroke 

Accept  keystroke  if  text  item 

What  actually  happens  when  an  item  is  told  to  perform  one  of  the  above  actions 
depends  on  the  type  of  the  item.  For  example,  when  asked  to  begin  previewing, 
a  button  item  inverts  its  label,  a  message  item  does  nothing,  a  slider  item  redraws 
the  shaded  area  of  its  slider  bar,  etc.^^ 

Writing  Your  Own  Event  You  may  want  to  handle  events  in  a  way  which  is  not  supported  by  this  default 

Handler  scheme.  For  example,  there  is  no  way  to  take  any  action  on  middle  mouse  button 

events.  To  do  so  you  must  extend  the  event  handling  functionality  by  replacing 
the  default  eventito-action  mapping  function  for  a  panel  or  panel  item.  Three 
attributes  have  been  defined  for  this  purpose: 

Table  9-3  Panel  Event  Handling  Attributes 


Attribute 

Argument  Type 

Default  Value 

PANEL_EVENT__PROC 

int  (*)  0 

panel  default_handle_event  () 

PANEL  BACKGROUND  PROC 

int  (*)  0 

panel  default  handle_event () 

PANEL_ACCEPT_KEYSTROKE 

boolean 

FALSE 

An  item’s  panel_EVENT_proc  is  called  when  an  event  falls  over  the  item. 
The  event  procedure  for  an  item  defaults  to  that  for  the  panel.  Thus  you  can 
change  the  event  procedure  for  aU  the  items  in  a  panel  by  specifying  your  own 
PANE  L_EVENT_P ROC  for  the  panel  before  the  panel  items  are  created.  The 
arguments  passed  to  the  event  procedure  are  the  item  (or  panel)  and  the  event. 


The  general  Sun  View  input  paradigm,  including  details  on  the  various  events,  is  covered  in  Chapter  6, 

Handling  Input. 

®  For  particulars,  see  the  Selection  subsection  under  each  item  type. 
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The  default  event  procedure,  which  implements  the  default  event-to-action  map- 
ping  described  on  the  previous  page,  is: 

panel_default_handle_event (object,  event) 

<Panel_item  or Panel>  object ; 

Event  *event; 


The  panel’s  PANEL_BACKGROUND_PROC  is  called  when  an  event  falls  on  the 
backgroimd  of  the  panel  (i.e.  an  event  whose  locator  position  does  not  fall  over 
any  item).  The  default  panel  background  procedure  is  also 
panel_def  ault_handle_event  ( ) ;  however,  the  various  actions  are  no- 
ops  for  the  panel.  Note  that  this  attribute  only  applies  to  a  panel;  it  has  no  mean¬ 
ing  for  an  individual  panel  item. 

The  attribute  PANEL_ACCEPT_KEYSTROKE  determines  whether  or  not  an  item 
or  panel  is  interested  in  keystroke  events.  If  this  is  TRUE,  the  item  or  panel 
under  the  cursor  is  given  keystroke  events  as  they  are  generated.  The  default 
behavior  sends  all  keystroke  events  to  the  text  item  with  the  caret,  independent  of 
the  cursor  position. 


In  addition  to  the  three  event  related  attributes,  three  event  codes  have  been 
defined: 


□  P ANEL_EVENT_DRAG_IN  —  the  item  or  panel  was  entered  for  the  first 
time  with  one  or  more  buttons  down. 

□  P  ANEL_E  VENT_MOVE_lN  —  the  item  or  panel  was  entered  for  the  first 
time  with  no  mouse  buttons  down. 


□  PANEL_EVENT_CANCEL  —  the  item  or  panel  is  no  longer  “current”  so  any 
operations  in  progress  should  be  canceled  (e.g.  cancel  previewing). 

The  panel  package  will  generate  these  events  as  appropriate  and  pass  them  to  the 
item’s  event  procedure  or  the  panel’s  background  procedure. 


The  event-to-action  mapping  is  performed  by  means  of  a  set  of  action  functions. 
If  you  haven’t  specified  an  event  procedure  for  the  item, 
panel_def  ault_handle_event  ( )  wiU  map  events  to  the  appropriate 
actions  by  calling  one  of  the  action  functions.  These  action  functions  have  been 
made  public  so  that,  if  you  replace  the  event  procedure  for  an  item,  you  can  ask 
the  panel  package  to  perform  one  of  the  default  actions  by  calling  the 
corresponding  action  function  from  your  new  event  procedure. 


The  action  functions  are  given  in  the  table  on  the  following  page. 
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Example 


Table  9-4  Panel  Action  Functions 


Definition 

Description 

panel  accept  key  (object,  event) 

<Panel  or  Panel  item>  object; 

Event  * event; 

Tells  a  text  item  to  accept  a  keyboard 
event.  Currently  ignored  by  non-text 
panel  items. 

panel_accept_menu (object,  event) 
<Panel or Panel_item>  object; 

Event  * event; 

TeUs  an  item  to  display  its  menu 
and  process  the  user’s  selection. 

panel  accept_preview (object ,  event) 
<Panel or Panel_item>  object; 

Event  * event; 

Tells  an  item  to  do  what  it  is  supposed 
to  do  when  selected,  including  completing 
any  previewing  feedback. 

panel_begin_preview (object,  event) 
<Pmel or Panel_Uem>  object; 

Event  * event; 

Tells  an  item  to  begin  any  feedback 
which  indicates  tentative  selection. 

panel_cancel_j)  review (object,  event) 
<Panel  or  Panel  item>  object; 

Event  *  event ; 

Tells  an  item  to  cancel  any  previewing 
feedback. 

panel  update__preview  (object ,  event) 
<Panel or Panel_item>  object; 

Event  *event; 

Tells  an  item  to  update  its  previewing 
feedback  (e.g.  redraw  the 
slider  bar  for  a  slider  item). 

In  most  of  the  action  routines,  only  the  event’s  location  and  shift  state  are  of 
interest.  When  previewing,  choices,  toggles  and  sliders  use  the  event’s  location 
to  determine  the  current  value.  Choices  use  the  shift  state  to  determine  whether 

to  advance  or  backup  the  current  choice.  panel_accept_key  ()  is  the  only 
action  function  to  make  use  of  the  actual  event  code. 


Suppose  you  are  implementing  dbxtool  and  want  to  have  the  buttons  in  the  com¬ 
mand  panel  execute  different  commands  depending  on  whether  they  were 
selected  with  the  left  or  middle  mouse  button.  For  example,  the  button  labeled 
next  might  behave  as  the  step  button  if  activated  with  the  middle  button.  When 
the  middle  button  is  depressed,  you  want  to  preview  an  alternate  label,  and  when 
it  is  released,  you  want  to  execute  the  dbx  command  corresponding  to  the  pre¬ 
viewed  label. 

You  can  get  get  this  functionality  by  replacing  the  event  procedure  for  each  of 
the  button  items  in  the  command  panel.  This  could  be  done  either  by  specifying 
a  default  event  procedure  for  all  the  items  when  the  panel  is  created: 

panel  =  window_create (frame,  PANEL, 

PANEL_EVENT_PROC,  dbx_event_proc, 

0); 

k, _ / 


or  by  specifying  a  the  event  procedure  as  each  panel  item  is  created: 


panel_create_it em (panel ,  PANEL_BUTTON , 

PANEL__EVENT__PROC,  dbx_event_proc, 

0); 
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Whenever  one  of  the  buttons  gets  an  event,  dbx_event_proc  ( )  will  be 
called  and  can  then  map  the  events  to  actions  as  it  sees  fit  The  code  for  the  new 
event  procedure  is  given  below.  Note  the  use  of  panel_client_data  to 
store  the  images  for  the  two  labels  for  each  item. 


dbx_event^roc  (item,  event) 

Panel_item  item; 

Event  * event; 

{ 

struct  dbx_data  *dbx_data;  /*  data  stored  with  each  item  */ 

Panel  panel; 

/*  First  get  my  private  data  for  this  item.  */ 

panel  =  (Panel)  pane l_get  (item,  PANEL_PARENT_PANEL)  ; 

dbx_data  =  (struct  dbx_data  *)  pane l_get (item,  PANEL_CLIENT_DATA) ; 

/*  See  if  this  is  an  event  of  interest.  */ 
switch  (event_action (event) )  { 

/*  middle  button  went  up  or  down  */ 
case  MS_MIDDLE: 

if  (event_is_down (event) )  { 

/*  middle  button  went  down,  so  change  the  button's  label 

*  image  to  reflect  its  middle  button  action. 

*/ 

panel_set  (item,  PANEL_LABEL_IMAGE,  dbx_data->middlej)r,  0)  ; 

/*  now  begin  the  normal  previewing  */ 
panel_begin_preview (item,  event) ; 

}  else  { 

/*  middle  button  went  up,  so  accept  the  previewing  */ 
panel_accept_preview (item,  event); 

/*  now  change  the  image  back  */ 

panel_set  (item,  PANEL_LABEL_IMAGE,  dbx_data->left_pr,  0); 

} 

break; 

/*  drag  into  item  with  button  down  */ 
case  P ANEL_EVENT_DRAG_IN : 

if  (window_get (panel,  WIN_EVENT_STATE,  MS_MIDDLE) )  { 

/*  middle  button  is  down,  so  treat  this  as  begin  preview. 

*/ 

panel_set (item,  P ANEL_LABEL_IMAGE ,  dbx_data->middle_pr,  0) ; 
panel_begin_preview ( item,  event ) ; 

} 

else 

/*  we  weren't  previewing,  so 

*  let  the  default  event  proc  handle  it. 

*/ 

panel_default_handle_event  (item,  event)  ; 
break; 
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/*  cancel  for  some  reason  */ 
case  PANEL_EVENT_CANCEL: 

if  (panel_get (item,  PANEL_LABEL_IMAGE)  == 
dbx_data->middle__pr)  { 

/*  we  were  previewing  —  cancel  it. 

*/ 

panel  cancel  preview (item,  event) ; 

panel_set  (item,  PANEL_LABEL_IMAGE,  dbx_data->left_pr,  0) ; 
}  else 

/*  we  weren't  previewing,  so 
*  let  the  default  event  proc  handle  it. 

*/ 

panel_default_handle_event (item,  event) ; 
break; 

/*  some  other  event  */ 
default : 

/*  we  don't  care  about  this  event  —  let  the  default 
*  event  proc  handle  it . 

*/ 

panel_default_handle_event (item,  event) ; 

} 

} 


The  final  step  is  to  modify  the  notify  procedure  for  each  button  to  perform  dif¬ 
ferent  actions  depending  on  which  mouse  button  was  released.  The  notify  pro¬ 
cedure  for  the  step/next  button,  for  example,  would  look  like: 


— 

next_step_notify__proc  (item. 

event) 

Panel_item  item; 

{ 

Event  * event; 

if  (event_action (event) 

==  MS_MIDDLE) 

/*  do  middle  button 

command,  "step"  */ 

else 

} 

/*  do  left  button  command,  "next”  */ 

J 

Translating  Events  from  In  the  case  of  a  scrollable  panel,  the  panel  is  larger  than  the  subwindow  in  at  least 

Panel  to  Window  Space  one  dimension.  If  the  panel  has  been  scrolled,  each  point  within  the  subwindow 

will  have  one  location  in  the  coordinate  space  of  the  panel  and  a  different  loca¬ 
tion  in  the  coordinate  space  of  the  subwindow.  Two  functions  are  provided  to 
translate  event  coordinates  from  panel  space  to  window  space,  and  vice  versa. 

If  you  read  your  own  events  with  window_r  ead._event  ( )  you  must 
translate  the  events  from  window  space  to  panel  space  with: 


^  window_read_event  ( )  is  described  in  Chapter  6, 
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Event  * 

panel_event (panel,  event) 

Panel  panel; 

Event  *event; 

To  go  from  panel  space  to  window  space,  use: 
Event  * 

panel_window_event (panel,  event) 
Panel  panel; 

Event  *event ; 


Figure  9-7  illustrates  the  image  browser  from  iconedit .  It  serves  as  an  exam¬ 
ple  of  when  to  use  pane  l_window_e  vent  ( ) .  If  the  user  presses  the  menu 
button  over  an  image,  then  he  gets  a  menu  showing  the  name  of  the  file  contain¬ 
ing  the  image: 

Figure  9-7  Image  Browser  Subframe  Using  panel_window_event  ( ) 


In  order  for  the  menu  to  be  displayed  in  the  correct  place  in  a  panel  which  has 
been  scrolled,  the  menu’s  location  must  be  specified  in  the  coordinates  of  the 
subwindow,  not  of  the  panel. 
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The  browser  is  implemented  as  a  panel  containing  buttons  having  the  images  as 
their  labels.  The  buttons  are  created  each  time  the  user  wants  to  browse  a  dif¬ 
ferent  set  of  images.  When  each  button  is  created,  the  name  of  the  file  containing 
the  image  is  stored  as  the  value  of  the  buttori’s  panel_CLIENT_DATA. 

Listed  below  is  the  event  procedure  shared  by  each  button.  There  is  a  global 
menu  containing  a  single  menu  item,  image_menu_item.  If  the  event  is  a 
right  mouse  button,  the  display  string  for  this  menu  item  is  set  to  the  file  name 
which  was  previously  stored  as  the  button’s  panel_CLIENT__DATA. 

Then  the  event  is  adjusted  from  panel  space  to  window  space,  and  the  menu  is 
displayed  at  the  proper  coordinates.  If  the  user  selects  from  the  menu,  the 
button’s  notify  procedure,  browser_items_notif  y_proc  ( ) ,  is  called,  so 
the  effect  is  the  samb  whether  the  item  is  selected  through  the  menu  or  directly. 


Note  that  for  aU  events  other  than  the  right  mouse  button,  the  panel’s  default 
event  procedure  is  called. 
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Alerts 


This  chapter  describes  the  alerts  package,  which  you  can  use  by  including  the  file 
<suntool/alert  .h>  in  your  program. 

This  chapter  is  divided  into  three  logical  sections.  Section  1  provides  a  brief 
introduction  to  alerts.  Section  2  explains  the  components  that  make  up  alerts. 
Sections  3  gives  program  fragments  that  introduce  most  of  the  alert  attributes. 

An  alert  is  a  pop-up  frame  that  contains  a  panel  to  notify  a  user  of  problems  or 
changes  that  require  their  attention.  An  alert  is  easUy  identified  visually  by  a 
large  black  arrow  that  sweeps  into  the  alert  window  from  the  left.  A  SunView 
application  can  use  alerts  to  notify  a  user  that  an  event  has  taken  place  or  to  ver¬ 
ify  that  a  user  requested  some  action.  Each  alert  that  pops  up  has  full  screen 
access.  That  is,  the  screen  is  frozen  until  the  user  responds  to  the  alert. 

Alerts  are  a  replacement  for  the  menu_prompt  ( )  facility.  Some  programs  will 
use  menu  prompts  instead  of  alerts  if  the  user  disables  alerts  in 
def  aultsedit.  Menu  prompts  offer  a  simple  box  with  text,  and  a  maximum 
of  two  choices. 

Alerts,  on  the  other  hand,  have  a  better  user  interface.  Alerts  provide  an 
attention-getting  alert  arrow,  buttons,  fonts,  beeps,  a  3-D  shadow,  and  so  on. 
Using  alerts,  you  can  offer  a  user  more  than  two  choices  of  action. 

Summary  Listing  and  Tables  To  give  you  a  feeling  for  what  you  can  do  with  alerts,  the  following  page  con¬ 
tains  a  list  of  the  available  alert  attributes  and  functions.  Many  of  these  are  dis¬ 
cussed  in  the  rest  of  this  chapter  as  they  occur  in  the  examples  and  elsewhere 
(use  the  Index  to  check).  AU  are  briefly  described  with  their  arguments  in  the 
alert  summary  tables  in  Chapter  19,  SunView  Interface  Summary: 

a  the  Alert  Attributes  table  begins  on  page  316; 

□  the  Alert  Functions  and  Macros  table  begins  on  page  3 1 8; 
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Alert  Attributes 

ALERT_BUTTON 

ALERT_MESSAGE_STRINGS_ARRAY_PTR 

ALERT_BUTTON_FONT 

ALERT_NO_BEEP ING 

ALERT_BUTTON_NO 

ALERT_OPTIONAL 

ALERT__BUTTON_YES 

ALERT_POSITION 

ALERT_MESSAGE_FONT 

ALERT_POSITION 

ALERT_MESSAGE_STRINGS 

ALERT_TRIGGER 

Alert  Functions 

alert_proinpt  (client_frame,  event,  attributes) 
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Uses  of  Alerts 


A  SimView  application  uses  alerts  to  display  messages  to  the  user,  who  can  then 
either  continue,  cancel,  or  choose  a  different  course  of  action.  Possible  uses  of 
alerts  include  the  following: 

o  Querying  whether  an  action  was  intended:  “Are  you  sure  you  want  to  Quit?” 

□  Notifying  a  user  of  a  current  state:  “Unrecognized  file  name.  No  files  match 

specified  pattern.” 


10.2.  The  Components  of 
an  Alert 


Figure  10-1  illustrates  the  visible  components  that  make  up  an  alert.  Each  com¬ 
ponent  is  described  below. 


Figure  10-1  An  Alert 


Alert  Arrow 


Each  alert  window  is  identifiable  as  an  alert  by  the  large  black  arrow  that  sweeps 
into  the  window  from  the  left. 


Multiple-Line  Text  Message  ^  multiple-line  text  message  describes  why  an  alert  appeared  and  what  to  do  in 

Do  you  really  uiant  to  exit  sunVieu,?  Order  to  Continue.  For  example,  if  the  user  tties  to  quit  SunView,  an  alert  witii 

the  message,  “Do  you  really  want  to  exit  SunView?”,  will  pop  up. 


Buttons 

[CanceT] 


Buttons  make  it  possible  to  give  the  user  a  choice  of  actions  when  warning  them 
that  an  event  has  taken  place.  Each  button  is  associated  with  a  string  that 
specifies  an  action. 

Many  alerts  have  a  default  button  which  is  indicated  by  a  double  outiine  (as  in 
the  Confirm  button  above).  If  an  alert  has  a  default  button,  then  the  pointer  will 
jump  to  this  button  when  the  alert  appears,  so  that  clicking  LEFT  will  take  the 
default  action.  The  pointer  is  moved  back  to  its  original  position  when  the  alert 
goes  away.  The  user  can  disable  pointer  jumping  by  setting 
SunView! Alert _Jump_Cursor  to  disabled  in  defaults  edit. 
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Positioning 

Beeping 


10.3.  alert_prompt  () 


10.4.  Building  an  Alert 


You  have  three  choices  for  alert  placement.  The  alert  may  be  screen-centered, 
client-centered,  or  client-offset. 

An  alert  may  be  specified  to  pop  up  with  or  without  a  beep.  The  default  is  to 
come  up  beeping  the  number  of  times  that  is  specified  in  def  aultsedit.  You 
may  set  your  alert  to  come  up  without  a  beep  even  if  the  user’s  default 
SunViewlAlertJBell  entry  in  def  aultsedit  is  to  come  up  beeping. 

There  is  only  one  function  in  the  alert  package,  alert_j3rompt  O  ;  it  creates 
an  alert,  pops  it  up  on  the  screen,  handles  user  interaction,  then  takes  down  the 
alert  and  returns  a  value. 

int 

alert_proinpt  (client_f rame,  event,  attributes) 

Frame  client_f  rame; 

Event  *event 

<attribute-list>  attributes; 

alert_prompt  ( )  displays  an  alert  whose  appearance  and  behavior  is 
specified  by  the  attribute  value  list  attributes.  It  does  not  return  a  value 
until  the  user  pushes  a  button  in  the  alert  or  the  default  trigger  event  or  its 
accelerator  is  seen.  By  default  the  alert  is  positioned  over  the  center  of 
client_f rame. 

If  you  supply  a  pointer  to  an  event  as  event  ,  it  wiU  be  filled  in  with  the  user 
event  which  dismissed  the  alert.  For  example,  if  the  users  pushes  a  button  by 
clicking  LEFT,  event_action  (event)  will  be  MS_LEFT.^^ 

The  possible  status  values  which  alert_j5rompt  { )  returns  are: 

□  ALERT_YES  —  the  user  pushed  the  “yes”  alert  button 

□  ALERT_NO  —  the  user  pushed  the  “no”  alert  button 

□  ALERT_F AILED  —  the  alert_prompt  ( )  failed  for  some  reason 

□  ALERT_TRI  GGERED  —  a  triggered  response  occurred 

□  Some  other  integer  —  the  user  pushed  some  other  button  than  “yes”  or  “no.” 

This  section  contains  code  fragments  that  illustrate  most  of  the  attributes  for  the 
alerts  package.  For  a  complete  list  and  explanation  of  the  alert  attributes,  see 
Chapter  19,  SunView  Interface  Summary.  Each  code  fragment  described  below 
is  organized  as  follows: 

o  Attributes  introduced  in  the  code  are  described 

□  An  illustration  of  the  alert  box  is  given 
o  The  code  is  listed  and  described. 


®  See  Chapter  6,  Handling  Input  for  an  explanation  of  the  Events. 
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For  a  complete  program  example  using  alerts,  see  filer  in  Appendix  A,  Example 
Progrcmis. 


Example  1  —  Messages  and  This  section  gives  two  code  fragments  in  order  to  illustrate  the  different  button 
Simple  Buttons  attributes.  The  buttons  allow  the  user  to  choose  an  action.  Each  alert  may  contain 

one  or  more  buttons;  the  default  is  for  no  buttons. 

Each  button  has  a  name  and  an  associated  value.  When  a  user  pushes  a  button, 
the  value  associated  with  the  button  is  returned. 

The  following  attributes  are  used  in  the  first  code  fragment.  STRINGS  "" 
ALERT_ME S S AGE_S TRINGS 

The  ALERT_MESSAGE_STRINGS  attribute  specifies  a  string  or  strings  to  be 
displayed  in  the  message  area  of  the  alert  panel. 

An  example  of  the  syntax  for  a  message  is: 

ALERT_MESSAGE_STRINGS , 

"The  text  has  been  edited.", 

"Empty  Document  will  discard  these  edits.  Please  confirm", 

0, 


The  ALERT_BUTTON  attribute  displays  a  string  in  a  button  and  associates  a 
value  to  it.  The  value  specified  with  the  string  is  returned  when  the  button  is 
pushed.  The  value  may  be  any  integer,  but  should  not  be  one  of  the  values 
predefined  by  the  alerts  package  (  alert_yes,  alert_no,  alert_failed, 
or  ALERT_TRIGGERED  ).  Figure  10-2  illustrates  an  alert  that  was  built  using 
the  attributes  ALERT_button.  It  contains  four  buttons  and  one  text  string. 
This  example  asks  the  user  what  part  of  the  country  they  are  from.  The  program 
fragment  is  listed  below. 

Figure  10-2  A  Simple  Alert 


- - - - 

result  =  alert_prompt ( 

(Frame)  client  frame, 
(Event*)  NULL 

ALERT_ME  S  SAGE_S  TRINGS 

- ^ 

"What  part 
0, 

ALERT_BUTTON, 

of  the  country  are  you  from?". 

"North", 

101, 

ALERT_BUTTON, 

"East", 

102, 

ALERT_BUTTON, 

"West", 

103, 

ALERT_BUTTON, 

"South", 

104, 
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switch  (result)  { 


case  101: 
/*handle 

case 

for 

someone 

from 

the 

North*/ 

break; 
case  102: 
/*handle 

case 

for 

someone 

from 

the 

East*/ 

break; 
case  103: 
/*handle 

case 

for 

someone 

from 

the 

West*/ 

break; 
case  104: 
/*handle 

case 

for 

someone 

from 

the 

South*/ 

break; 
case  ALERT 

FAILED : 

/* 

*  Possibly  out  of  memory  or  fds; 

*  attempt  to  get  information  another  way 
*/ 

break; 


Yes  and  No  Buttons 


Usually  you  will  want  to  map  your  buttons  to  “yes”  and  “no”  actions.  To  make 
this  possible,  two  special  buttons  are  triggered  by  predefined  keyboard  accelera¬ 
tors.  Yes  (confirm,  do  it)  is  mapped  to  the  ( Return  J  key.  No  (cancel,  don’t  do  it) 
is  mapped  to  the  ( Stop  I  key  (usually  ILIJ). 

The  SunView  event  name  for  yes  is  ACTlON_DO_IT.  The  SunView  event 
name  for  no  is  ACTION  STOP. 


The  following  attributes  are  used  in  this  example: 


The  ALERT_BUTTON_YES  attribute  associates  a  string  with  the  accelerated 
YES  button.  The  value  ALERT_YES  is  returned  by  alert_prompt  ( )  if  the 
user  pushes  this  button,  or  types  f  Return  1.  Only  one  instance  of  this  attribute  is 
allowed;  subsequent  instances  are  ignored. 

The  YES  button  image  will  have  a  different  button  image  than  the  other  buttons. 
It  will  appear  as  a  regular  button  image  with  a  double  outline. 

An  example  of  the  syntax  is: 

ALERT_BUTTON_YES,  "Confirm,  discard  edits". 

The  ALERT  BUTTON  NO  attribute  associates  a  string  with  the  accelerated  NO 
button.  The  value  returned  if  the  user  pushes  this  button,  or  types  [  gtopj ,  wiU  be 
ALERT  NO.  Only  one  instance  of  this  attribute  is  allowed;  subsequent  instances 
are  ignored. 
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An  example  of  the  syntax  is: 

ALERT__BUTTON_NO,  "Cancel", 

Figure  10-3  illustrates  the  alert  that  is  generated  by  the  following  code.  It  con¬ 
tains  two  buttons  and  two  text  strings.  The  buttons  give  the  user  two  choices:  to 
empty  a  document,  discarding  any  edits  they  may  have  made,  or  to  cancel  the 
operation  completely. 

Figure  10-3  AYES/NO  Alert 


The  text  has  been  edited. 

Empty  Document  will  discard  these  edits.  Please  confirm. 


[Cancel] 


, - - — 

int  result; 

result  =  alert^rompt  ( 

(Frame) window, (Event*) NULL, 

ALERT_MESSAGE_STRINGS , 

"The  text  has  been  edited.", 

"Empty  Document  will  discard  these  edits. \ 

Please  confirm.", 

0, 

ALERT_BUTTON_YES,  "Confirm,  discard  edits", 

ALERT_BUTTON_NO,  "Cancel " , 

0); 

switch (result) { 
case  ALERT_YES: 

/*discard  edits*/ 
break; 

case  ALERT_NO: 

/*cancel  the  Empty  Document  request  */ 
break; 

case  ALERT_FAILED : 
break; 
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Example  2  —  Changing  Fonts  The  default  font  used  for  alert  message  text  is  the  Qient  Frame’s  font,  if  one  has 

been  specified;  or  else  it  is  the  same  as  SunViewlFont.  The  default  font  for  alert 
buttons  is  the  same  as  that  specified  for  menus  in  MenusIFont  in  defaultsedit,  or 
screen.b.l4,  if  no  default  is  specified. 

You  may  prefer  to  use  different  fonts  within  alerts.  For  example,  you  might  want 
to  set  off  the  text  in  an  alert  box  from  the  text  in  the  Client’s  frame  by  using  the 
bold  version  of  the  Client  Frame’s  default  font. 

The  ALERT_MESSAGE_FONT  and  ALERT_BUTTON_FONT  attributes  con¬ 
trol  the  font  setting  for  the  alert  message  text  and  alert  buttons,  respectively. 

Figure  10-4  illustrates  an  alert  in  which  the  message  string  is  printed  in 
couiier.b.  16.  The  code  fragment  shown  below  it  illustrates  how  to  set  the 
attribute’s  value  using  the  font  library.  It  also  illustrates  the  use  of  multiple  mes¬ 
sage  strings. 

Figure  10-4  An  Alert  with  Boldface  Message  Strings 


It^s  crackers  to  slip  a  rozzer 
the  dropsy  in  snide ^ 
vith  a  fuzzy  udder. 

— Daimon  Runyon 

[Confirm^ 


- - - 

Event  alert_event; 

int  result  =  alert_prompt (base_frame,  &alert_event , 
ALERT_MESSAGE_STRINGS , 

"It's  crackers  to  slip  a  rozzer", 

"the  dropsy  in  snide,", 

"with  a  fuzzy  udder.", 

"  — Daimon  Runyon" , 

0, 

ALERT_BUTTON_YES,  "Confirm", 

ALERT_BUTTON_NO ,  " Cancel " , 

ALERT_MESSAGE_FONT , 

pf_open ("/usr/lib/fonts/fixedwidthfonts/cour.b. 16) , 
ALERT_POSITION ,  ALERT_CLIENT_CENTERED , 

0); 


Example  3  —  Using  Triggers  Often  you  will  want  to  give  the  user  the  choice  of  using  mouse  buttons  or  key¬ 
board  accelerators  instead  of  push  buttons  to  respond  to  an  alert.  Triggers  give 
you  this  option  by  making  it  possible  to  specify  an  accelerator  or  mouse  action 
for  a  choice. 

For  example,  the  text  window  uses  an  alert  to  ask  the  user  where  to  split  a  win¬ 
dow.  A  left  mouse  button  click  is  the  trigger  that  responds  to  this  alert. 
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The  following  attribute  is  used  when  specifying  a  trigger; 

The  ALERT_TRIGGER  attribute  allows  the  application  to  specify  a  SunView 
event  which  should  cause  the  alert  to  return.  The  default  is  not  to  return  a  value 
unless  a  button  has  been  pushed  or  the  other  YES/NO  accelerators  are  seen. 
When  an  event  is  triggered,  the  value  returned  will  be  alert_trigger.  An 
example  of  the  message  syntax  is  as  follows. 

ALERT_TRIGGER,  event. 

Figure  10-5  illustrates  the  alert  that  is  generated  by  the  following  code.  This  alert 
contains  one  button  and  a  triggered  response.  When  this  alert  comes  up,  the  user 
may  split  the  existing  window  into  two  windows,  or  can  dismiss  the  alert  by 
pushing  the  Cancel  New  Window  button.  This  example  also  shows  how  alerts 
can  effectively  use  ah  event  to  collect  information  about  the  way  a  user  reacted  to 
an  alert.  See  Chapter  6,  Handling  Input,  for  a  fuU  explanation  and  list  of  aU  pos¬ 
sible  events. 

Figure  10-5  An  Alert  Using  Triggers  and  Events 
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Event  event; 
int  result; 

result  =  alert^ronpt  ( 

(Frame) windbw, 

& event, 

ALERT_NO_BEEP I NG ,  1 , 

ALERT_MESSAGE_STRINGS , 

"Move  pointer  to  where  new  window  should" , 
"appear,  then  click  the  left  mouse  button ." , 
"Otherwise,  push  \"Cancel  New  Window. "\, 

0, 

AIiERT_BUTTON_NO,  "Cancel  New  Window", 

ALERT_TRIGGER,  MS_LEFT, 

0>; 

switch  (result)  { 

case  ALERT_TRIGGERED: 

(void)  create_new_window_at_pos (event_x (&event) , 

event_y (Sevent) ) , 

break; 

case  ALERT_NO: 

break;  /*  don't  create  new  window  */ 
case  ALERT_FAILED: 

/*  alert  failed,  possibly  out  of  memory  or  fds  */ 


You  may  specify  in  your  code  to  have  an  alert  pop  up  without  a  beep  as  shown 
above.  Generally,  beeping  is  reserved  for  any  event  which  occurs  unexpectedly. 
If  the  alert  is  in  response  to  a  user  request,  it  should  not  beep. 

The  following  attribute  is  used  to  specify  no  beeping  for  an  alert. 

The  ALERT_N0_BEEPING  attribute  allows  the  SunView  application  to  specify 
that  no  beeping  should  take  place  regardless  of  default  sedit  setting.  The 
default  for  this  option  is  FALSE;  that  is,  beep  as  many  times  as  the  defaults  data¬ 
base  specifies. 
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ttysw_input ( ) 
ttysw_input 0 
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TTY_PID  . 

Talking  Directly  to  the  TTY  Sub  window  .... 
An  Example . 
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TTY  Subwindows 


The  tty  (or  terminal  emulator)  subwindow  emulates  a  standard  Sun  terminal,  the 
principal  difference  being  that  the  row  and  column  dimensions  of  a  tty  subwin¬ 
dow  can  vary.  You  can  run  arbitrary  programs  in  a  tty  subwindow;  perhaps  its 
main  use  is  to  run  a  shell  within  a  window. 

To  see  tty  subwindows  in  use,  run  the  standard  tools  shelltool(l)  and 
gfxtool(l). 

Header  Files  Programs  using  tty  subwindows  must  include  the  file  <suntool/tty .  h>. 

Summary  Listing  and  Tables  To  give  you  a  feeling  for  what  you  can  do  with  tty  subwindows,  the  following 

page  contains  lists  of  the  available  tty  subwindow  attributes,  functions  and  mac¬ 
ros.  Many  of  these  are  discussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the 
Index  to  check).  AH  are  briefly  described  with  their  arguments  in  the  tty  subwin¬ 
dow  summary  tables  in  Chapter  19,  SunView  Interface  Summary: 

□  the  TTY  Subwindow  Attributes  table  begins  on  page  376; 

□  the  TTY  Subwindow  Functions  table  begins  on  page  376; 

□  the  TTY  Subwindow  Special  Escape  Sequences  table  begins  on  page  yil. 
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TTY  Subwindow  Attributes 

TTY_ARGV 

TTY  CONSOLE 

TTY  PAGE_MODE 

TTY  QUIT  ON  CHILD  DEATH 
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11.1.  Creating  a  TTY 
Subwindow 


11.2.  Driving  a  TTY 
Subwindow 


ttysw_input ( ) 


Like  all  Sun  View  windows,  you  create  a  tty  subwindow  by  calling 
window_create  ( )  with  the  appropriate  type  parameter,  as  in: 


Tty  tty; 

tty  =  window_create (frame,  TTY,  0); 

> 

V _ 

_ / 

By  default,  the  tty  subwindow  will  fork  a  shell.  If  you  want  to  start  the  tty 
subwindow  with  another  program,  say  vi,  you  can  do  so  by  specifying  the  name 
of  the  program  to  run  via  the  TT  Y_ARGV  attribute: 

,  —  - - ^ 

tinclude  <suntool/sunview.h> 

#include  <suntool/tty .h> 

char  *my_argv[]  =  {  "vi",  0  }; 

main  () 

{ 

Tty  tty; 

Frame  frame; 

frame  =  window_create (0,  FRAME,  0); 

tty  =  window_create (frame,  TTY,  TTY_ARGV,  my_argv,  0); 
window_main_loop (frame)  ; 

} 

V - - 


NOTE  You  can  only  have  one  tty  subwindow  per  process. 

You  can  drive  the  terminal  emulator  programmatically.  There  are  procedures 
both  to  send  input  to  the  terminal  emulator  (as  if  the  user  had  typed  it  in  the  tty 
subwindow)  and  to  send  output  (as  if  a  program  running  in  the  tty  subwindow 
had  output  it).  The  two  effects  are  similar  to  the  mapi  /  mapo  functions  in 
~  /  .  tty  swr  c  that  permit  a  user  to  bind  a  character  sequence  to  a  function 
key.^^ 

You  can  send  input  to  a  tty  subwindow  programmatically  with  the  function: 
int 

ttysw_input (tty,  buf ,  len) 

Tty  tty; 
char  *buf; 
int  len; 

ttysw_input  { )  appends  the  character  sequence  in  buf  that  is  len  charac¬ 
ters  long  onto  tty’s  input  queue.  It  returns  the  number  of  characters  accepted. 
The  characters  are  treated  as  if  they  were  typed  from  the  keyboard. 
ttysw_input  ( )  provides  a  simple  way  for  a  window  program  to  send  input  to 
a  program  running  in  its  ttysubwindow. 


See  SunOS  Reference  Manual. 
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ttysw_input  {} 


Example:  ttyjo 


11.3.  TTY  Subwindow 
Escape  Sequences 

Standard  ANSI  Escape 
Sequences 


Use  tty  sw_output  ( >  to  output  to  a  tty  subwindow, 
int 

ttysw_output (tty,  buf,  len) 

Tty  tty; 
char  *buf; 
int  len; 


ttysw__output  ( )  runs  the  character  sequence  in  buf  that  is  len  characters 
long  through  the  tenninal  emulator  of  tty.  It  returns  the  number  of  characters 
accepted.  The  effect  is  similar  to  executing 


- — 

A 

$cho  character  ^sequence  >  /dev/ttyN 

_ ) 

where  ttyA  is  the  pseudo-tty  associated  with  the  tty  subwindow.  One  use  of 
ttysw_output  0  is  to  send  the  escape  sequences  listed  in  the  next  section  to 
the  tty  subwindow. 


Appendix  A,  Example  Programs,  gives  the  listing  for  tty_io,  a  program  which 
uses  tty_output  ( )  to  output  strings  of  characters  to  a  tty  subwindow. 


The  tty  subwindow  accepts  the  same  ANSI  escape  sequences  as  the  raw  Sun  con¬ 
sole, with  the  following  few  exceptions: 

□  The  effect  of  the  bell  control  character  CTRL-G  (0x07)  in  a  tty  subwindow 
depends  on  how  the  user  has  set  the  two  options  Audible_Bell  and 
Visible_Bell  in  the  SunView  category  in  default  sedit  (1).  If 
Audible_Bell  is  Enabled,  the  bell  wiU  ring.  If  Visible _Bell  is  Enabled,  the 
window  will  flash. 

□  The  graphics  rendition  sequences  ESC  [  4m  (underline)  and  ESC  [  Im  (bold 
“extra-bright”)  operate  correctly.  On  the  Sun  console,  these  sequence 
always  invert  subsequent  characters,  whereas  the  tty  subwindow  only  inverts 
when  sent  ESC  [  7m  (stand-out). 

o  The  effect  of  the  bold  “extra-bright”  graphics  rendition  sequence  ESC  [  Im  in 
a  tty  subwindow  depends  on  the  user’s  setting  for  the  Bold_style  option  in 
the  Tty  category  of  default  sedit. 

a  Unsupported  graphics  rendition  mode  escape  sequences  have  the  same  effect 
as  that  chosen  for  bold  “extra-bright”.  On  the  Sun  console,  everything 
inverts. 

□  The  Set  Scrolling  sequence  ESC  [Or,  which  enables  vertical  wrap  mode  on 
the  Sun  terminal,  has  no  effect  in  a  tty  subwindow. 


^  See  the  console(4s)  manual  page  in  the  SunOS  Reference  Manual  for  a  full  list  of  escape  sequences. 
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□  You  can  modify  termcap  (5)  if  you  need  further  control  over  what  gets 
displayed  in  the  different  modes.  The  two-character  termcap  symbols  for 
each  of  the  modes  are: 

so  standout 
us  underline 
md  bold  (extra  bright) 

Special  Escape  Sequences  Escape  sequences  have  been  defined  by  which  the  user  can  get  and  set  attributes 

of  both  the  tty  subwindow  and  the  frame  which  contains  it  For  example,  the 
user  can  type  an  escape  sequence  to  open,  close,  move  or  resize  the  frame, 
change  the  label  of  the  frame  or  the  frame’s  icon,  etc.  These  escape  sequences 
are  described  in  Table  19-33,  TTY  Subwindow  Special  Escape  Sequences,  in 
Chapter  19,  SunView  Interface  Summary. 

Example:  tty_io  For  an  example  of  setting  the  frame’s  label  via  a  tty  subwindow  escape  sequence, 

see  the  program  tty_io,  listed  in  Appendix  A,  Example  Programs. 

11.4.  Reading  and  Writing  You  cannot  use  the  tty  subwindow’s  file  descriptor  returned  by  WIN_FD  to  read 

to  a  TTY  Subwindow  and  write  characters  to  it.  You  can  use  TT  y_tty_FD  attribute  to  get  the  file 

descriptor  of  the  pseudo-tty  associated  with  the  tty  subwindow.  You  can  then 
use  this  to  read  and  write  to  the  pseudo-tty  using  standard  UNIX  I/O  routines. 
Note  that  TTY_TTY_FD  is  the  file  descriptor  of  the  pseudo-tty,  not  the  file 
descriptor  of  the  tty  subwindow  returned  by  WIN_FD.  The  latter  is  used  for 
low-level  window  manipulation  procedures. 

11.5.  The  Program  in  the  You  use  the  tty_argv  attribute  to  pass  the  name  of  the  program  to  run  to  the 

TTY  Subwindow  tty  subwindow.  The  program  runs  as  a  forked  child  in  the  tty  subwindow. 

TT  Y_P  ID  You  can  use  TT  Y_P  ID  to  monitor  the  state  of  the  child  process  running  in  the  tty 

window  via  the  Notifier  using  L  notify_interpose_wait3_func0  .  The  client’s 
wait  3  ( )  function  gets  called  when  the  state  of  the  process  in  the  tty  subwin¬ 
dow  changes.  The  setup  is  something  like  this: 


The  waits  { )  function  can  then  do  something  useful,  such  as  destroying  the 
tty  window  or  starting  up  another  process  in  the  tty  subwindow.  Here  is  a  code 
fragment  that  detects  the  death  of  its  tty  subwindow’s  child.  It  turns  off  the 
default  behavior  of  a  tty  subwindow,  which  is  to  quit  when  the  child  process  dies. 


Revision  A,  of  May  9,  1988 


216  SunView  1  Progranuner’s  Guide 


static  Notify_value 

nv_wait3 (ttysw,  pid,  status,  rusage) 

Tty  ttysw; 

int  pid; 

union  wait  *status; 

struct  rusage  *rusage; 

{ 

int  child_j)id; 

notify_next_wait3_func (ttysw,  pid,  status,  rusage); 
if  (!  (WIFSTOPPED(*status) ) )  { 

window_set (ttysw, 

TTY_QUIT_ON_CHILD_DEATH,  FALSE, 

TTY_ARGV,  nQr_argv, 

0)  ; 

child_j>id  =  (int)  window_get  (ttysw,  TTY_PID) ; 
notify_interpose_wait3_func  (ttysw,  nTy_wait3,  child_pid)  ; 

} 

return  NOTIFY_DONE; 

} 


You  can  set  TTY_PID  as  well  as  get  it,  but  if  you  set  it  then  you  are  responsible 
for  setting  the  notif  y_interpose_wait3_f  unc  ( )  to  catch  the  child’s 
death,  and  for  making  the  standard  input  and  standard  output  of  the  child  go  to 
the  pseudo-tty. 

Talking  Directly  to  the  TTY  If  you  set  TTY_ARGV  to  TTY_ARGV_D0_N0T_F0RK,  this  teUs  the  system  not 

Subwindow  to  fork  a  child  in  the  tty  subwindow.  In  combination  with  tty_fd,  this  allows 

the  tool  to  use  standard  VO  routines  to  read  and  write  to  the  tty  subwindow.^^ 
This  simplifies  porting  terminal-oriented  graphics  programs,  which  interact  with 
the  user  on  the  model  of  write  a  prompt. . .  read  a  reply y  to  SunView.  However, 
in  most  cases  you  should  redesign  programs  to  use  a  real  windowing  interface 
made  up  of  SunView  components. 

An  Example  The  typein  program  in  Appendix  A,  Example  Programs  reads  and  writes  directly 

to  its  tty  subwindow,  using  SunView’s  window_main_loop  { )  control  struc¬ 
ture. 

The  following  example  preserves  the  fiow  of  control  of  a  typical  UNIX  applica¬ 
tion,  using  notif  y_do_di spat ch  { )  to  ensure  that  the  Notifier  gets  called. 
Read  Section  17.6,  Porting  Programs  to  SunView,  for  more  information  on  using 
the  Notifier  in  this  way. 


#define  BUFSIZE  1000 
static  int  my_done ; 

static  Notify_value 
my_notice_destroy (frame,  status) 
Frame  frame; 

Destroy_status  status; 


®  This  capability  makes  obsolete  the  woik-around  required  in  the  3,0  and  3.2  releases  of  SunView  if  you 
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if  (status  !=  DESTROY_CHECKING)  { 
my_done  =1; 

(void)  notify_stop  ()  ; 

} 

return  (notify_next_destroy_func (frame,  status)); 


main (argc,  argv) 
int  argc; 

char  *argv[]; 

{ 

Frame  ba  se_f  rame ; 

Tty  ttysw; 

int  tty_fd; 

char  buf [BUFSIZE] ; 

my_done  =0; 

base_frame  =  window_create (NULL,  FRAME, 

FRAME_ARGC_PTR_ARGV,  &argc,  argv, 

0); 

ttysw  =  window_create  (base__frame,  TTYSW, 

TTY^ARGV,  TTY_ARGV_DO_NOT_FORK, 

0); 

tty_fd  =  (int) window_get (ttysw,  TTY_TTY_FD) ; 
dup2 (tty_fd,  0); 
dup2 (tty_fd,  1); 

(void) notify_interpose_destroy_func (base_f rame,  my_notice_destroy) ; 
window_set (base_frame,  WIN_SHOW,  TRUE,  0); 

(void) notify_do_dispatch 0 ; 

puts  {prompt Jojiser)  ; 

while  (gets  (buf))  { 

if  (my_done)  /*  continue  until  destroyed  */ 
break; 

/* 

*  TMs  is  where  the  meat  of  the  program 

*  would  be  if  this  were  a  real  program. 

*/ 

puts (buf) ; 

} 

exit  (0) ; 


wanted  a  window  program  to  read  and  write  from  its  own  tty  subwindow. 
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Menus 


Summary  Listing  and  Tables 


The  SunView  menu  package  allows  you  to  chain  individual  menus  together  into 
a  collection  known  as  a  walking  menu.  A  menu  contains  menu  items,  some  of 
which  may  have  a  small  arrow  pointing  to  the  right.  This  indicates  to  the  user 
that  if  he  or  she  slides  the  mouse  to  the  right  of  that  item,  a  pull-right  menu  will 
appear.  Menus  can  be  strung  together  in  this  fashion,  so  that  the  user  “walks”  to 
the  right  down  the  chain  of  menus  in  order  to  make  a  selection. 

The  definitions  necessary  to  use  walking  menus  are  found  in  the  file 
<suntool/walkmenu .  h>,  \yhich  is  included  by  default  when  you  include 
the  file  <suntool/sunview .  h>. 

The  most  useful  sections  to  read  first  are  the  first  three.  Section  12.1,  Basic 
Menu  Usage,  introduces  the  basic  routines  and  gives  some  simple  examples. 
Section  12.2,  Components  of  Menus  &  Menu  Items,  outlines  the  components  of 
menus  and  menu  items  and  introduces  common  terms.  Section  12.3,  Examples, 
gives  more  examples  of  using  menus.  Section  12.7,  Callback  Procedures,  is  for 
advanced  users  who  need  to  understand  the  subtleties  of  the  callback  mechanism. 

The  listing  for  font  menu,  a  program  which  builds  on  some  of  the  examples 
given  throughout  the  chapter,  is  given  in  Appendix  A,  Example  Programs. 

To  give  you  a  feeling  for  what  you  can  do  with  menus,  the  following  two  pages 
list  the  available  menu  attributes,  functions  and  macros.  Many  of  these  are  dis¬ 
cussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to  check).  All  are 
briefly  described  with  their  arguments  in  the  menu  summary  tables  in  Chapter 
19,  SunView  Interface  Summary: 

a  the  Menu  Attributes  table  begins  on  page  335; 

o  the  Menu  Item  Attributes  table  begins  on  page  339; 

□  the  Menu  Functions  table  begins  on  page  34 1 . 
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Menu  Attributes 

MENO  ACTION  IMAGE 

MENU_LAST_EVENT 

MENU  ACTION  ITEM 

MENU_LEFT_MARGIN 

MENU  APPEND  ITEM 

MENU_MARGIN 

MENU  BOXED 

MENU_NCOLS 

MENU  CENTER 

MENU_NITEMS 

MENU  CLIENT  DATA 

MENU_NROWS 

MENU  COLUMN  MAJOR 

MENU_NOTIFY_PROC 

MENU  CLIENT  DATA 

MENU_NTH_ITEM 

MENU  DESCEND  FIRST 

MENU_PARENT 

MENU  DEFAULT 

MENU_PULLRIGHT_DELTA 

MENU  DEFAULT  ITEM 

MENU_PULLRI GHT_I MAGE 

MENU  DEFAULT  SELECTION 

MENU_PULLRI GHT_ITEM 

MENU  FIRST  EVENT 

MENU_REMOVE 

MENU  FONT 

MENU_REMOVE_I TEM 

MENU  GEN  PROC 

MENU_REPLACE 

MENU  GEN  PULLRIGHT  IMAGE 

MENU_REPLACE_ITEM 

MENU  GEN  PULLRIGHT_ITEM 

MENU_RIGHT_MARGIN 

MENU  IMAGE  ITEM 

MENU_SELECTED 

MENU  IMAGES 

MENU_SELECTED_ITEM 

MENU  INITIAL  SELECTION 

MENU_SHADOW 

MENU  INITIAL  SELECT I ON_EXPANDED 

MENU_STAy_UP 

MENU  INITIAL  SELECT I ON_SELECTED 

MENU_STRINGS 

MENU  INSERT 

MENU_STRING_ITEM 

MENU  INSERT  ITEM 

MENU_TI TLE_IMAGE 

MENU_ITEM 

MENU_TITLE_ITEM 

MENU  JUMP  AFTER  NO  SELECTION 

MENU_TYPE 

MENU  JUMP  AFTER_SELECTION 

MENU  VALID  RESULT 

Menu  Item  Attributes 

MENU  ACTION  IMAGEt 

MENU_INACTIVE 

MENU  ACTION  ITEMf 

MENU_INVERT 

MENU  ACTION  PROC 

MENU  LEFT_MARGINf 

MENU  APPEND  ITEMf 

MENU_MARGINf 

MENU  BOXEDf 

MENU_PARENTf 

MENU  CENTERf 

MENU_PULLRIGHT 

MENU  CLIENT  DATAf 

MENU_PULLRI GHT_IMAGEf 

MENU  FEEDBACK 

MENU_PULLRI GHT_I TEMf 

MENU  FONTf 

MENU_RELEASE 

MENU  GEN  PROCf 

MENU_RELEASE_I MAGE 

MENU  GEN  PROC  IMAGE 

MENU_RIGHT_MftRGINf 

MENU  GEN  PROC  ITEM 

MENU_SELECTEDf 

MENU  GEN  PULLRIGHT 

MENU_STRINGf 

MENU  GEN  PULLRIGHT  IMAGEf 

MENU_STRING_ITEMf 

MENU  GEN  PULLRIGHT  ITEMf 

MENU_TYPEf 

MENU_IMAGE 

MENU_VALUE 

MENU  IMAGE_ITEMf 

o 
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_ _ Menu  Functions _ 

menu_create (attributes) 
menu_create_item (attributes) 
me  nu_d.es  troy  (menu_object) 

menu_destroy_with_proc (menu_ob ject ,  destroy_proc) 
void  (*destroy_proc) () ; 
menu_find (menu,  attributes) 
menu_set  (menu_ob  ject.,  attributes) 
menu_show (menu,  window,  event,  0) 
menu_return_item (menu,  menu_item) 
menu_ret ur n_va lue  (menu,  menu_item) 
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12.1.  Basic  Menu  Usage 


The  basic  usage  of  menus  is  to  first  create  the  menu  with  menu_create  ( } , 
then  display  it  when  desired  with  menu_show  ( ) : 

Menu 

menu_create (attributes) 

<attribute-list>  a 1 1  r ibute  s ; 


caddr_t 

menu_show (menu,  window,  event,  0) 

Menu  menu ; 

Window  window; 

Event  *event ; 

Like  the  creation  routines  for  other  SunView  objects,  menu_cr  eate  ( )  takes  a 
null-terminated  attribute  list  and  returns  an  opaque  handle.  menu_show  ( ) 
displays  the  menu,  gets  a  selection  from  the  user,  and,  by  default,  returns  the 
value  of  the  menu  item  the  user  has  selected,  window  is  the  handle  of  the  win¬ 
dow  over  which  the  menu  is  displayed;  event is  the  event  which  causes  the 
menu  to  come  up.  The  final  argument  is  provided  so  that  attributes  may  be 
passed  in  the  future;  at  present  it  is  ignored. 

Use  the  routines  menu_set  ( )  and  menu_get  ( )  to  modify  and  retrieve  the 
values  of  attributes  for  both  menus  and  menu  items: 


int 

menu_set (menu_ob ject,  attributes) 
<Menu  or  Menu  jtem>  menu_ob  j  ec t  ; 
<attribute~list>  attributes; 


caddr_t 

menu_get (menu_object,  attribute [,  optional_arg] ) 

<Menu  or  Memjtem>  menu_ob  ject; 

Menu_attribute  attribute; 
caddr_t  optional_arg; 

All  the  attributes  applying  to  menus  and  menu  items  are  listed  in  the  two 
corresponding  tables  Menu  Attributes  and  Menu  Item  Attributes  in  in  Chapter  19, 
SunView  Interface  Summary.  Common  attributes  applying  to  both  menus  and 
menu  items  appear  in  both  tables. 

The  pages  which  follow  contain  three  examples  of  basic  menu  usage. 


®  Canvases  and  panels  have  their  own  coordinate  spaces  separate  from  the  window’s  coordinate  space. 
Note  that  event  is  in  the  coordinate  space  of  the  window,  not  of  the  canvas  or  panel. 
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Let’s  take  a  very  simple  example  —  a  menu  with  two  selectable  items 
represented  by  the  strings  ‘On’  and  ‘Off’: 


The  attribute  MENU_STRINGS  takes  a  list  of  strings  and  creates  an  item  for  each 
string.  Note  that  the  first  zero  in  the  above  caU  terminates  the  list  of  strings,  and 
the  second  zero  terminates  the  entire  attribute  list. 


CAUTION  The  menu  package,  in  contrast  to  the  panel  package,  does  not  save  strings 
which  you  pass  in.  So  you  should  either  pass  in  the  address  of  a  constant,  as  in 
the  example  above,  or  static  storage,  or  storage  which  you  have  dynamically  allo¬ 
cated. 


Typically  you  call  menu__show  { )  from  an  event  procedure,^®  upon  receiving 
the  event  which  is  to  cause  display  of  the  menu.  In  the  code  fragment  below,  we 
display  the  menu  on  right  button  down: 


menu_show  () ,  by  default,  returns  the  value  of  the  item  which  was  selected.  If 
the  item  was  created  with  MENU  STRINGS  its  value  defaults  to  its  ordinal  posi¬ 
tion  in  the  menu,  starting  with  So  in  the  above  example,  selecting  ‘On’ 
would  cause  1  to  be  returned,  while  selecting  ‘Off’  would  cause  2  to  be  returned. 


You  can  specify  that  menu_show  ( )  return  the  item  itself,  rather  than  return  the 
value  of  the  selected  item.  Do  this  by  setting  menu_NOTIFY_proc  to  the 
predefined  notify  procedure'^^  inenu_return_item  ( ) ,  as  in: 


™  See  Chapter  6.  Handling  Input,  for  a  discussion  of  event  procedures. 

The  value  of  menu  items  not  created  with  MENU  STRINGS  defaults  to  zero.  You  can  explicitly  specify 
the  values  for  menu  items  via  the  attributes  MENU_IMAGE_ITEM,  MENU_STRING_ITEM,  or  MENU  VALUE. 
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Example  2: 


It’s  easy  to  build  up  more  complex  menus  out  of  simple  ones.  The  next  example 
creates  a  menu  with  two  items,  ‘Bold*  and  ‘ Italic each  of  which  shares  the  on- 
off  menu  from  the  previous  example  as  a  puU-right: 


menu  =  menu  create (MENU_ITEM, 

MENU  STRING, 

"Bold" , 

MENU  PULLRIGHT, 

on  off  menu , 

0, 

MENU  ITEM, 

_ 

MENU  STRING, 

"Italic" , 

MENU  PULLRIGHT, 

on  off  menu , 

0, 

0)  , 

The  most  flexible  way  to  create  a  menu  item  in-line  in  a  menu_create  { )  caU 
is  by  using  MENU_ITEM.  In  contrast  to  MENU_S THINGS,  which  allows  you  to 
specify  only  the  display  strings  of  the  items,  MENU_ITEM  takes  as  its  value  a 
nuU-terminated  attribute  list  which  may  contain  any  attributes  applying  to  menu 
items.^^ 

The  value  of  MENU_STRING  is  the  item’s  display  string;  the  value  of 
MENU_PULLRIGHT  is  the  handle  of  the  item’s  puU-right  menu.  (Note  that  you 
must  already  have  created  the  menu  before  giving  it  as  the  value  for 
MENU  PULLRIGHT.) 


Example  3:  The  menu  package  can  accommodate  images  as  well  as  strings.  The  example 

below  creates  a  menu  with  a  single  item  labelled  ‘tools’.  When  the  user  puUs 
right,  he  brings  up  a  menu  showing  the  icons  of  three  SunView  tools  — 
def aultsedit, iconedit,  and  f ontedit. 


73  For  a  complete  list  of  such  attributes,  see  the  Menu  Item  Attributes  table  in  in  Ch^ter  19,  SunView 
Interface  Summary. 
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In  order  to  pass  an  image  into  the  menu  package  you  need  a  pointer  to  a  memory 
pixrect  containing  the  image.  One  common  way  to  create  such  an  image  is  by 
first  using  iconedit  to  create  the  image  and  save  it  to  a  file.  You  then  include  the 
file  in  your  program,  and  use  the  mpr_st  at  ic  ( )  macro  to  create  a  memoiy 
pixrect: 


static  short  d_defaults[]  =  { 
tinclude  <iinages/def aultsedit .  icon> 

}; 

mpr_static  (default s_pr,  64,  64,  1,  d__defaults)  ; 

static  short  d_icon [ ]  =  { 
finclude  <images/iconedit . icon> 

}; 

mpr_static  (icon_pr,  64,  64,  1,  d_icon) ; 

static  short  d_font[]  =  { 

♦include  <iinages/fontedit  .icon> 

}; 

mpr_static (font_pr,  64,  64,  1,  d_font) ; 

tool_menu  =  menu_c reate (MENU_IMAGES, 

&defaults_pr,  &icon_pr,  &font_pr,  0, 
0); 

menu  =  menu_create (MENU_ITEM, 

MENU_STRING,  "tools”, 

MENU_POLLRIGHT,  tool_menu, 

0, 

0); 

- — _ _ _ 


The  attribute  MENU_IMAGES  is  analogous  to  MENU_STRINGS,  It  takes  a  list  of 
images  (pointere  to  pixrects)  and  creates  a  menu  item  for  each  image. 
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12.2.  Components  of 

Menus  &  Menu  Items 


This  section  gives  an  overview  of  the  most  important  components  of  menus  and 
menu  items.  Detailed  discussion  and  examples  follow  later  in  the  chapter. 


Menus 


Visual  Components 


Generate  Procedures 


Notify  Procedures 


Client  Data 


The  text  for  a  menu  is  rendered  in  the  menu’s  font,  which  you  may  specify  via 
MENU_FONT.  A  menu  has  a  shadow',  you  can  specify  the  shadow’s  pattern,  or 
disabk  the  shadow  entirely,  via  MENU_SHADOW.  You  can  give  a  title  to  a  menu 
viaMENU_TlTLE_lMAGE  or  MENU_TITLE_ITEM.’^4  gy  default,  a  menu’s 
items  are  laid  out  vertically;  you  can  specify  that  the  items  be  laid  out  horizon¬ 
tally  or  in  a  two-dimensional  matrix  via  MENU_NCOLS  and  MENU_NROWS. 

You  may  specify  a  generate  procedure  for  a  menu,  which  will  be  called  just 
before  the  menu  is  displayed.  This  allows  you  to  implement  context-sensitive 
menus  by  dynamically  modifying  the  menu,  or  even  replacing  it  entirely.”^^ 

The  menu’s  notify  procedure  is  called  after  the  user  makes  a  selection.  By  using 
a  notify  procedure,  you  can  perform  an  action  or  alter  the  resultor  alter  the  result 
to  be  returned  by  menu_show  ( ) 

The  menu’s  client  data  field,  accessible  through  MENU_CLIENT__DATA,  is 
reserved  for  the  application’s  use.  You  can  use  this  attribute  to  associate  a 
unique  identifier,  or  a  pointer  to  a  private  structure,  with  a  menu. 


Menu  Items  A  menu  contains  an  array  of  items.  To  retrieve  a  menu’s  nth  item,  use 

MENU  NTH  I TEM.  To  retrieve  the  total  number  of  items  in  a  menu  use 
menu”nitems. 

The  same  menu  item  can  appear  in  more  than  one  menu. 

CAUTION  Menu  items,  unlike  panel  items,  are  counted  starting  with  one. 


Menu  Items 

Representation  on  the  Screen  A  menu  item  is  either  displayed  as  a  string  or  an  image  (a  pointer  to  a  pixrect).  If 

the  item  has  another  menu  associated  with  it  using  the  menu_pullright  attri¬ 
bute,  then  it  is  a  pull-right  item. 


The  tide  is  nothing  more  than  an  inverted,  ncm-selectable  item.  It  does  not  automatically  appear  at  the  top 
of  the  menu  —  it  is  your  responsibility  to  position  it  where  you  want  it 

See  example  8  in  Section  12.7,  Callback  Procedures,  later  in  the  chapter. 

Notify  procedures  are  discussed  in  detail  in  Section  12.7,  Callback  Procedures., 
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Item  Values 


Item  Generate  Procedures 


Item  Action  Procedures 


Client  Data 


Each  menu  item  has  a  \alue.  By  default  an  item’s  value  is  the  initial  ordinal 
position  of  the  item  if  it  was  created  with  MENU_STRINGS;  otherwise  the 
default  value  is  zero.  You  can  set  an  item’s  value  explicitly  when  you  create  the 
item  with  menu_STRING_item  or  menu_image_item.  You  can  also  expli¬ 
citly  set  an  item’s  value  with  menu_value.  However,  if  an  item  is  a  puU-right, 
then  its  MENU_VALUE  is  the  value  of  its  puU-right  menu.  This  means  that  only 
“leaf’  menu  items  without  submenus  have  a  true  value. 

As  mentioned  in  Section  12.1,  Basic  Menu  Usage,  menu_show  ( )  by  default 
returns  the  value  of  the  item  the  user  has  selected.  Since  menu  items  are  counted 
starting  from  one,  a  return  value  of  zero  from  menu_show  { )  would  represent 
the  null  selection.^^  However,  you  may  explicitly  set  the  value  of  a  menu  item  to 
zero.  If  you  do,  then  a  return  value  of  zero  could  represent  either  a  legal  value 
for  the  selected  item  or  an  error.  To  tell  whether  or  not  the  result  was  valid,  caU 
menu_get()  with  the  boolean  MENU_VAL I D_RESULT.  A  return  value  of 
TRUE  means  that  the  result  was  valid;  FALSE  means  that  the  value  is  invalid. 

As  with  the  menu  as  a  whole,  you  may  specify  a  generate  procedure  for  each 
menu  item,  to  be  called  just  before  the  item  is  displayed. 

The  action  procedure  of  a  menu  item  is  analogous  to  the  notify  procedure  of  a 
menu.  This  is  your  chance  to  do  something  immediately  based  on  the  user’s 
selection. 

Menu  notify  procedures  and  item  action  procedures  differ  in  when  they  are 
called.  If  the  user  chooses  an  item  in  a  pull-right  menu,  the  notify  procedures  (if 
any)  for  the  menus  higher  up  in  the  chain  leading  to  the  pull-right  will  be  called, 
whereas  the  action  procedures  (if  any)  for  the  chosen  menu  item  and  menu  items 
under  it  (“to  its  right”)  wiU  be  caUed.^^ 

Each  menu  item  has  a  client  data  field,  accessible  through 
MENU_CLIENT_DATA,  which  is  reserved  for  the  application’s  use.  You  can  use 
this  attribute  to  associate  a  unique  identifier,  or  a  pointer  to  a  private  structure, 
with  each  menu  item. 


This  is  why  menu  items  are  counted  starting  with  one,  rather  than  zero:  so  that  a  zero  return  value  would 
represent  the  null  selection  whether  the  menu  show  ( )  was  returning  the  value  of  the  selected  item  or  the  item 
itself. 

Action  procedures  are  discussed  in  detail  in  Section  12.7,  Callback  Procedures. 
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Item  Margins 


The  diagram  below  illustrates  the  layout  of  a  menu  item: 


Figure  12-1  Layout  of  a  Menu  Item 


margin 

margin 

left 

margin 

string 

puU-right 
arrow 
(if  any) 

right 

margin 

margin 

margin 

MENU_MARGIN  represents  the  margin,  in  pixels,  around  an  item  in  a  menu.  Its 
default  value  is  1. 

You  can  set  an  individual  item’s  margin  by  setting  the  menu  item.  To  set  the 
margins  for  all  items  in  a  menu,  set  the  menu’s  margin. 

You  can  adjust  the  horizontal  placement  of  text  in  menu  items  with 
MENU_LEFT_MARGIN  and  MENU_RIGHT_MARGIN.^^ 

As  with  MENU_MARGIN,  the  left  and  right  margins  can  be  set  either  for  an  indi¬ 
vidual  menu  item  or  for  the  menu  itself,  in  which  case  the  settings  will  apply  to 
all  the  items  in  the  menu.  CThe  attributes  MENU_FONT  and  menu_BOXED  also 
work  this  way.) 


12.3.  Examples 

Example  4: 


Our  next  example  will  show  several  variations  on  a  simple  menu  that  could  be 
used  for  selecting  font  point  sizes.  The  default  form  is  shown  to  the  left. 


You  could  create  the  items  with  MENU_STRINGS,  as  in  the  previous  example. 
Alternately,  you  could  create  the  menu  with  no  items,  then  use  menu_set  { )  to 

append  the  items  to  the  menu:^® 

_  — - 

m  =  menu_create (0) ; 

for  (i  =  8;  i  <=  18;  i  +=  2) 

menu  set (m,  MENU_STRING_ITEM,  int_to_str (i) ,  i,  0) ; 


The  placement  of  images  is  currently  not  affected  by  the  settings  of  the  left  and  right  margins. 

*0  Note  that  using  MENU  STRING  ITEM  with  menu_set  ( )  has  the  effect  of  an  implicit  append.  Several 
attributes  are  provided  to  explicitly  add  items  to  a  menu  —  see  Table  12-1,  Attributes  to  Add  Pre-Existing  Menu 
Items,  later  in  this  section. 


Nr  microsystems 


Revision  A,  of  May  9, 1988 


Chapter  12  —  Menus  23 1 


MENU_STRING_ITEM  takes  as  values  the  item’s  string  and  its  value. 

Now  let’s  see  some  of  the  ways  in  which  the  appearance  of  this  basic  menu  can 
be  altered. 

By  setting  MENU_INACTIVE  to  TRUE  for  an  item,  you  can  “gray  out”  the  item 
to  indicate  to  the  user  that  it  is  not  currently  selectable. 

The  menu  to  the  left  could  be  produced  by: 


for  (i  =  4;  i  <=  6;  i++)  { 

item  =  menu_get (m,  MENU_NTH_ITEM,  i) ; 
menu_set (item,  MENU_INACTIVE,  TRUE,  0) ; 

} 


Inactive  items  do  not  invert  when  the  cursor  passes  over  them. 

The  can  menu_set  (m,  MENU_BOXED,  TRUE,  0 )  wiU  cause  a  single¬ 
pixel  box  to  be  drawn  around  each  item.  With  the  default  margin  of  1  pixel,  this 
will  result  in  two-pixel  lines  between  each  item. 


Increasing  the  margin,  by  setting  MENU_MARGIN  to  5,  wiU  cause  the  items  to 
spread  out  evenly,  and  the  boxes  to  appear  as  individual  boxes  rather  than  divid¬ 
ing  lines. 


You  can  control  the  layout  of  the  items  within  a  menu  with  the  attributes 
MENU_NCOLS  and  MENU_NROWS.  Suppose  you  wanted  the  menu  to  be  laid  out 
horizontally  instead  of  vertically: 


AU  you  need  do  is  specify  at  create  time  that  the  menu  will  have  6  columns  with 
acaUsuchas  menu_set  (m,  MENU_NCOLS,  6,  0). 

You  can  use  menu_nC0LS  or  menu_nrows  to  create  two-dimensional  menus, 
as  well.  ThecaU  menu_set  (m,  MENU_NCOLS,  3,  0)  will  cause  the 
menu  package  to  begin  a  second  row  after  the  first  three  columns  have  been  filled 
with  items: 
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The  previous  example  specified  that  the  menu  have  3  columns.  Specifying  that  it  J 
have  2  rows  via  MENU_NR0WS  would  have  the  same  effect.  Items  are  laid  out 
from  upper  left  to  lower  right,  in  “reading  order,”  regardless  of  how  the  layout  is 
specified. 


The  only  time  you  need  to  specify  both  the  number  of  rows  and  the  number  of  ^ 
columns  is  when  you  want  to  fix  the  size  of  the  menu,  regardless  of  how  many 
items  it  contains.  Setting  menu__nC0LS  to  3  and  menu_nrows  to  3  would  pro¬ 
duce: 

If  both  dimensions  of  the  menu  are  fixed  and  more  items  are  given  than  will  fit, 
the  excess  items  will  not  appear. 
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You  can  remove  the  menu’s  shadow  by  setting  menu_SHADOW  to  nuU: 

The  menu  package  provides  three  predefined  pixrects  for  the  menu  shadow.  The 
call  menu_set  (m,  MENU_SHADOW,  &menu_gray25_pr )  produces  the 
25  percent  gray  pattern  shown  on  first  menu  below.  Note  that  these  are  pixrects, 
not  pixrect  pointers.  The  other  two  patterns  are  produced  by  using 
menu_gray50_pr  and  menu_gray75__pr: 


8 

8 

5* 

8  S 

18 

'IJi 

18 

ft 

ft 

18  1 

12 

y 

12 

ft 

12  1 

14 

V 

14 

s 

14  1 

16 

V 

IG 

1 

IG  1 

18 

18 

's' 

18 

'y 

y 

yyyyyyy’yy^ 

.'s 

Example  5:  Let’s  take  the  size  menu  from  the  previous  example  and  use  it  to  create  the  more 

complex  menu  shown  below,  which  the  user  could  use  to  select  both  a  font  fam¬ 
ily  and  a  point  size  within  the  family.  This  illustrates  the  multiple  usage  of  a  sin¬ 
gle  menu.  Pulling  right  over  any  of  the  items  in  the  family  menu  will  bring  up 
the  menu  for  selecting  point  size,  as  shown  on  the  left. 
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Courier 
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By  using  MENU_ITEM,  we  can  give  each  item  in  the  font  family  menu  its  string, 
the  font  in  which  to  render  the  string,  and  the  size  menu  as  a  pull-right: 
- - - 

family_menu  =  nienu_create  ( 


MENU  ITEM, 

MENU_STRING, 

"Courier” , 

MENU_FONT, 

cour. 

MENU_PULLRIGHT , 
MENU_ITEM, 

size  menu. 

0, 

MENU_STRING, 

"Serif", 

MENU  FONT, 

serif. 

MENU_PULLRI GHT , 

size_menu. 

0, 

MENU  ITEM, 

MENU_STRING, 

"aplAPLGIJ", 

MENU_FONT, 

apl. 

MENU  PULLRIGHT, 

size_menu. 

0, 

MENU  ITEM, 

MENU_STRING, 

"CMR", 

MENU  FONT, 

cmr. 

MENU_PULLRI GHT , 

size_menu. 

0, 

MENU  ITEM, 

MENU_STRING, 

"Screen" , 

MENU_FONT, 

screen. 

MENU_PULLRIGHT, 

size_menu. 

0, 

Suppose  the  font  family  menu  had  already  been  created,  and  we  wanted  to  add 
the  size  menu  as  a  pull-right  to  each  item  of  the  existing  menu.  We  could  do  this 
using  the  attributes  menu_nitems  and  menu_nth_item.  The  loop  below 
iterates  over  each  item  in  the  menu,  retrieving  the  item’s  handle  and  setting  the 
pull-right  for  the  item: 


for  (i  =  (int)menu_get  (family_inenu,  MENU_NITEMS)  ;  i  >  0;  i) 
menu_set  (menu_get  (family_inenu,  MENU_NTH_ITEM,  i)  , 

MENU  PULLRIGHT,  size_menu,  0) ; 


mictDsystems 


Revision  A,  of  May  9,  1988 


234  SunView  1  Programmer’s  Guide 


Example  6; 


Courier  =^ 
Serif 
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Screen 


You  can  insert  new  items  into  an  existing  menu  with  menu_INSERT.  For 
example,  suppose  you  want  to  insert  blank  lines  into  the  font  family  menu,  to 
indicate  grouping: 

You  can  do  this  by  inserting  non-selectable  items  into  the  menu: 


r  - 

menu_set (family_menu, 

MEND_INSERT, 

2, 

menu_create_it em (MENU_STRING,  ” ” , 

MENO_FEEDBACK,  FALSE, 

0)  , 

0); 

menu_set (family_menu, 

MENU_INSERT, 

5, 

menu_get  (family_menu,  MEND_NTH_ITEM,  3), 

0); 


MENU__INSERT  takes  two  values:  the  number  of  the  item  to  insert  after,  and  the 
new  item  to  insert.  Disabling  MENU_FEEDBACK  makes  the  item  non-selectable. 

The  above  example  uses  inenu_create_item  ( )  to  explicitly  create  the  item 
to  be  inserted.  Usually  menu  items  are  created  implicitly,  using  the  attributes 
described  in  Table  12-2,  Menu  Item  Creation  Attributes,  in  the  next  section. 

NOTE  menu_create_item  ( )  does  not  set  the  MENU_RELEASE  attribute  by 

default,  so  that  the  resulting  item  will  not  be  automatically  destroyed  when  its 
parent  menu  is  destroyed.  This  is  in  contrast  to  implicitly  created  menu  items  — 
see  Section  12.5,  Destroying  Menus. 
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In  addition  to  menu_INSERT,  there  are  several  other  attributes  you  can  use  to 
add  pre-existing  menu  items  to  a  menu.^^  They  are  summarized  in  the  following 
table. 

Table  12-1  Attributes  to  Add  Pre-Existing  Menu  Items 


Attribute 

Value  Type  Description 

MENU  APPEND_ITEM 

Menu  item  Append  item  to  end  of  menu. 

MENU  INSERT 

int.  Menu  item  Insert  new  item  after  nth  item 

(use  n=0  to  prepend). 

MENU  INSERT  ITEM 

Menu_item  (old) , 

Menu  item  <  new)  Insert  new  item  after  old  item. 

MENU_REPLACE 

int.  Menu  item  Replace  nth  item  with  specified  item. 

MENU  REPLACE  ITEM 

Menu  item(old). 

Menu  item  (new)  Replace  old  item  with  new  item 

in  the  menu  (old  item  is  not  replaced 
in  any  other  menus  it  may  appear  in). 

81  To  delete  items  from  a  maiu,  use  MENU  REMOVE  or  MENU_REMOVE_ITEM,  described  in  the  Menu 
Attributes  table  in  in  Chapter  19,  SunView  Interface  Summary. 
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Example  7: 


Frame 
Fani  ly  ={> 

Si  ze  =>  i 


Bold 


On 

Italic!  Off 


For  the  next  example  we  will  attach  the  on-off,  family  and  size  menus  of  the  pre- 
vious  examples  as  pull-rights  to  a  higher-level  menu  for  selecting  fonts: 


font_m6nu  =  menu  create  ( 

N 

MENU_P  OLLRI GHT_ 

ITEM, 

"Frame", 

frame  menu. 

MENU_PULLRIGHT_ 

ITEM, 

"Family" , 

family  menu. 

MENU_PULLRI GHT_ 

ITEM, 

"Size", 

size  menu. 

MENU_P  ULLRI GHT_ 

ITEM, 

"Bold", 

on  off  menu. 

MENU_PULLRIGHT 

ITEM, 

"Italic", 

on  off  menu. 

0>; 

V 

MENU_PULLRIGHT_ITEM  takes  a  String  and  a  menu  as  values.  It  creates  an 
item  represented  by  the  string  and  with  the  menu  as  a  pull-right. 

Note  that  on_of  f  menu  is  used  as  a  pull-right  for  both  the  bold  and  the  italic 
menu  items,  and  that  the  size_menu  appears  both  as  a  puU-right  from  main 
level  f  ont__menu  and  from  each  item  in  f  amily_menu.  This  demonstrates 
that  a  menu  may  have  more  than  one  parent.  However,  recursive  menus  are  not 
allowed  —  if  Ml  is  a  parent  of  M2,  M2  (or  any  of  its  children)  may  not  have  Ml 
as  a  child.  Displaying  such  a  recursive  menu  will  probably  result  in  a  segmenta¬ 
tion  fault. 


The  ‘Frame’  item  takes  as  its  pull-right  the  menu  which  has  been  retrieved  from 
the  frame  using  WIN_MENU. 


The  programfontjnenu,  printed  in 
ftirther  on  the  above  examples. 


Appendix  A,  Example  Programs,  builds 
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12.4.  Item  Creation  The  attribute  MENU_ITEM,  introduced  in  Example  2,  suffices  to  create  any  type 

Attributes  of  menu  item.  However,  several  attributes  are  provided  for  convenience  as  a 

shorthand  way  to  create  items  with  common  attributes.  These  attributes,  along 
with  the  types  of  values  they  take  and  the  type  of  item  they  create,  are  summar¬ 
ized  in  the  following  table: 

Table  12-2  Menu  Item  Creation  Attributes 


Attribute 

Value  Type 

Type  of  Item  Created 

MENU_ACT ION_IMAGE 

image,  action  proc 

Image  item  w/action  proc. 

MENU_ACT ION_ITEM 

char  *,  action  proc 

String  item  w/action  proc. 

MENU_GEN_PULLRIGHT_IMAGE 

Pixrect  *,  proc 

Image  item  with 
generate  proc  for  pull-right. 

MENU_GEN_PULLRIGHT_ITEM 

char  *,  proc 

String  item  with 
generate  proc  for  pull-right. 

MENU_IMAGE__ITEM 

Pixrect  *,  value 

Image  item  w/value. 

MENU_IMAGES 

list  of  Pixrect  * 

Multiple  image  items. 

MENU_PULLRIGHT_IMAGE 

Pixrect  *,  Menu 

Image  item  w^ull-right. 

MENU_PULLRIGHT_ITEM 

char  *,  Menu 

String  item  w/puU-right. 

MENU_S  TRING_I TEM 

char  *,  value 

String  item  w/value. 

MENU_STRINGS 

list  of  char  * 

Multiple  string  items. 

We  could  now  create  the  menu  in  Example  2  more  compactly  by  using 

MENU_PULLRIGHT_ITEM  instead  of  MENU_ITEM: 
- - — 

m  =  menu_create  (MENU_PULLRIGHT_ITEM,  "Bold",  on_of f_inenu, 

MENU_PULLRIGHT_ITEM,  "Italic”,  on_of f_inenu, 

0), 

V _ _ . 
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12.5.  Destroying  Menus  Both  menus  and  menu  items  are  destroyed  with  the  function: 

void 

menu_destroy (menu_ob ject ) 

<Menu  or  Menu_item>  menu_ob  j  ect  ; 


CAUTION  Watch  out  for  dangling  pointers  when  using  a  menu  item  in  multiple  menus.  The 
attribute  MENU_RELEASE  (which  takes  no  value)  controls  whether  or  not  a 
menu  item  is  automatically  destroyed  when  its  parent  menu  is  destroyed. 
MENU_RELEASE  is  set  to  TRUE  by  default  for  menu  items  created  in-line  via 
the  menu  item  creation  attributes.  This  can  lead  to  dangling  pointers,  if  the  same 
menu  item  appears  multiple  times,  because  calling  menu_destroY  ( )  can  lead 
to  items  being  destroyed  multiple  times.  This  warning  also  applies  to  pull-rights 
which  are  used  multiple  times.  To  prevent  this  error,  remove  multiple 
occurrences  of  an  item  or  pull-right  before  destroying  a  menu. 

Calling  menu_destro Y_with_j3roc  { )  instead  of  menu_destroy  ( ) 
when  you  want  to  destroy  a  menu  lets  you  specify  a  procedure  to  be  called  as  the 
menu  or  menu  item  is  destroyed,  lets  you  specify  a  procedure  to  be  called  every 
time  a  particular  menu  or  menu  item  is  about  to  be  destroyed: 

void 

menu_destroy_with_j5roc  (nienu_object,  destroy_proc) 

<Menu  or  Menu_item>  menu_ob  j  ec t  ; 
void  (*destroy_proc) () ; 

Your  destroy  procedure  should  be  of  the  form: 

void 

destroy_jproc  (menu_ob  ject ,  type) 

<Menu  or Menu_item>  menu_ob ject; 

Menu_attribute  type; 

For  menus,  menu_ob  ject  is  the  menu  and  the  type  parameter  is 
MENU_MENU;  for  menu  items,  menu_ob  ject  is  the  item  and  the  type  param¬ 
eter  is  MENU  ITEM. 
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12.6.  Searching  for  a  Menu  The  function  menu_f  ind  { )  lets  you  search  through  a  menu  (and  its  children) 
Item  to  find  a  menu  item  meeting  certain  criteria: 

Menu_item 

menu_f ind (menu,  attributes); 

Menu  menu; 

<attribute-list>  attributes; 

For  example,  the  following  call  searches  for  the  menu  item  whose  string  was 
“Load  New  File”.  menu_f  ind  ( )  will  return  itNULLif 

— - - , 

whose  string  was  "Load  New  File" ; 


By  default,  menu_f  ind  ( )  uses  a  “deferred”  search  —  searching  all  the  items 
in  a  menu  before  descending  into  any  puU-rights  which  may  be  present.  By  set¬ 
ting  MENU_DESCEND_FIRST  (which  takes  no  value),  you  can  force  a  depth- 
first  search. 

If  multiple  attributes  are  given,  menu_f  ind  ( )  will  find  the  first  item  matching 
all  the  attributes. 

The  following  attributes  are  recognized  by  menu_f  ind  ( ) : 


Table  12-3 


Mem  Attributes  Recognized  by  menu_f  ind  ( ) 


MENU_ACTION 

MENU_CL I ENT_D AT A 

MENU_FEEDBACK 

MENU_FONT 

MENU_GEN_PROC 

MENU_GEN_PULLRIGHT 

MENU_IMAGE 

MENU  INACTIVE 


MENU_INVERT 
MENU_LEFT_MARGIN 
MENU_MARGIN 
MENU_PARENT 
MENU_PULLRIGHT 
MENU_R I GHT_MARG IN 
MENU__STRING 
MENU  VALUE 
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12.7.  Callback  Procedures  When  you  call  menu_show  ( ) ,  the  menu  package  displays  the  menu,  gets  a 

selection  from  the  user,  and  undisplays  the  menu.  The  menu  package  ^ows  you 
to  specify  callback  procedures  which  will  be  called  at  various  points  during  the 
invocation  of  the  menu.  These  let  you  create  and  modify  menus  or  respond  to 
the  user’s  actions,  on  the  fly,  at  the  time  the  user  brings  up  the  menu.  There  are 
three  types  of  callback  procedures:  generate  procedures  (so  named  because  they 
are  called  before  the  menu  or  item  is  displayed,  allowing  the  application  to  gen¬ 
erate  or  modify  the  menu  on  the  fly),  notify  procedures  (for  menus)  and  action 
procedures  (for  menu  items)  which  are  called  after  the  user  has  made  a  selection. 

Flow  of  Control  in  The  callback  mechanism  gives  you  a  great  deal  of  flexibility  in  creating,  combin- 

inema_show  ( )  ing  and  modifying  menus  and  menu  items.  This  flexibility  comes  at  the  price  of 

some  complexity,  however.  To  take  advantage  of  it,  it  is  necessary  to  understand 
when  the  callback  procedures  are  called  after  you  invoke  menu_show  ( ) . 

For  purposes  of  explanation,  the  diagrams  below  divide  the  process  of  displaying 
a  menu  and  getting  the  user’s  selection  into  two  stages,  the  display  stage  and  the 
notification  stage. 
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Figure  12-3  Notification  Stage  of  Menu  Processing 


From  Display  Stage 


Return  from  menu_show  ( ) 


Generate  Procedures  The  first  argument  to  a  generate  procedure  is  either  a  menu  or  menu  item  depend¬ 

ing  on  whether  it’s  a  menu_GEN_proc  or  a  menu_GEN_proc_item.  Also 
passed  in  is  an  operation  indicating  at  which  point  in  the  processing  of  the  menu 
the  generate  procedure  is  being  called.  The  operation  parameter  is  of  type 
Menu_generate,  and  may  be  MENU_DISPLAY,  MENU_DlSPLAY_DONE, 
MENU  NOTIFY  or  MENU  NOTIFY  DONE.^2 


NOTE  The  menu  package  uses  the  fullscreen  access  mechanism  when  displaying  the 
menu.  Writing  to  the  screen  while  under  fullscreen  access  will  probably  cause 
your  program  to  deadlock,  so  your  generate  procedure  should  not  access  the 
screen  when  called  with  an  operation  of  MENU_DISPLAY  or 
MENU  DISPLAY  DONE. 


For  a  detailed  explanation  of  when  the  generate  procedures  are  called  in  relation  to  the  other  callback 
procedures,  see  the  diagrams  in  the  next  subsection.  Flow  of  Control  in  menu_show  ( > . 
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There  are  three  types  of  generate  procedures  —  menu  item  generate  procedures, 
menu  generate  procedures,  and  pull-right  generate  procedures.  A  description 
and  example  of  each  is  given  below. 

Menu  Item  Generate  Procedure  A  generate  procedure  attached  to  a  menu  item  has  the  form: 

Menu_item 

menu_item_gen_proc (item,  operation) 

Menu_item  item; 

Menu_generate  operation; 

You  can  specify  a  menu  item  generate  procedure  via  menu_GEN_PROC. 


Example  8: 


The  most  common  use  of  menu  item  generate  procedures  is  to  modify  the  item’s 
display  string.  The  program  listed  below  registers  a  generate  procedure, 
toggle_proc  ( ) .  If  it  has  been  called  from  the  MENU_DI  SPLAY  stage  of 
processing,  it  toggles  the  text  of  the  ‘Redisplay’  item  on  the  frame  menu. 


#include  <suntool/sunview.h> 

Menu_item  toggle_proc () ; 
int  toggle  =  0; 

main  {) 

{ 

Window  frame  =  window_create (NULL,  FRAME,  0); 
Menu  menu  =  window_get (frame,  WIN_MENU) ; 

Menu_item  item  =  menu_find (menu, 

MENU_STRING,  "Redisplay",  0) 

menu_set (item  ,  MENU_GEN_PROC,  toggle_proc,  0); 
window_main_loop (frame) ; 

} 

Menu_item 

toggle_proc (mi,  op) 

Menu_item  mi; 

Menu  generate  op; 


{ 


switch  (op)  { 

case  MENU_DISPLAY: 
if  (toggle)  { 

menu_set (mi, 

MENU_STRING,  "Redisplay  has  been  seen", 

0)  ; 

}  else  { 

menu_s  e  t  ( mi , 

MENU_STRING,  "Redisplay", 

0)  ; 

} 

toggle  =  ! toggle ; 
break; 

case  MENU__DISPLAY_DONE: 
case  MENU  NOTIFY: 
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Menu  Generate  Procedure 


Example  9: 


case  MENU_NOTIFY_DONE : 
break; 


} 

return  mi;  /*  item  handle  always  returned  */ 


The  ‘Zoom ’/‘Unzoom’  item  in  the  SunVkw  frame  menu  also  uses  this  technique 
to  toggle  its  display  string.  Note  that  since  this  item  knows  how  to  modify  itself, 
you  could  put  it  in  other  menus  and  get  the  same  behavior.  A  generate  procedure 
for  a  menu  item  allows  the  application  to  be  called  even  when  it  has  no 
knowledge  of  or  control  over  the  call  to  menu_show  ( ) . 

A  generate  procedure  attached  to  a  menu  has  the  form: 

Menu 

menu_gen_proc (m,  operation) 

Menu  m; 

Menu_generate  operation; 

You  can  specify  a  menu  generate  procedure  via  the  attribute  menu_GEN_PROC. 

We  will  take  as  an  example  a  menu  allowing  the  user  to  list  different  groups  of 
files.  When  the  user  makes  a  selection,  we  generate  a  menu  containing  the 
correct  set  of  files: 


List  dot  files  =» 

I 

clock  1 
shelltool  1 
iconedit  | 

List  all  files. 

The  relevant  functions  are  listed  on  the  next  page.  The  first, 
initialize_menu  ( ) ,  creates  the  three  menu  items,  giving  each  of  them  the 
generate  procedure  list__f  lies  ( ) ,  and  a  unique  identifier  as 
MENU_C  L I ENT_D AT A . 

Remember  that  list_f  lies  { )  is  called  in  four  different  situations  by 
menu_show  ( ) 

D  When  the  operation  is  MENU_DISPLAy,  the  puU-right  is  being  asked  to 
display  its  menu,  so  list_f  lies  { )  calls  the  function 
get_f  ile_names  ( )  (not  shown)  to  get  the  appropriate  list  of  file  names, 


See  the  diagrams  in  the  earlier  subsection.  Flow  of  Control  in  menu_show  { ) . 
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and  adds  each  name  in  the  list  to  the  menu. 

□  When  list_f  lies  ( )  is  called  with  operation  set  to 
MENU_DISPLAY_DONE,  the  menu  of  generated  file  names  is  no  longer 
being  displayed.  list_files()  cleans  up  by  destroying  the  old  menu  of 
file  names,  replacing  it  with  a  fresh  menu  with  the  same  generate  procedure. 
It  returns  the  handle  of  this  new  menu. 

□  When  list_f  lies  ( )  is  called  with  an  operation  of  MENU_NOTIFY 

or  MENU_NOTlFY_DONE,  the  menu  is  returned  unaltered. 

- 

#define  DOT  0 
tdefine  BIN  1 
tdefine  ALL  2 

static  void 
initialize_menu (menu) 

Menu  menu ; 

{ 

m  =  menu_create {MEND_GEN_PROC,  list_files, 
MEND_CLIENT_DATA,  DOT, 

0); 

menu_set (menu, 

MENU_PULLRIGHT_ITEM,  "List  dot  files",  m, 

0); 

m  =  menu_create (MENU_GEN_PROC,  list_files, 

MENU_CLIENT_DATA,  BIN, 

0); 

menu_set  (menu, 

MENU_PULLRIGHT_ITEM,  "List  bin  dir",  m, 

0); 

m  =  menu_create (MENU_GEN_PROC,  list_files, 

MENU_CLIENT_DATA,  ALL, 

0)  ; 

menu_set  (menu, 

MENU_PULLRIGHT_ITEM,  "List  all  files",  m, 

0); 

} 

static  Menu 

list_files (m,  operation) 

Menu  m; 

Menu_generate  operation; 

{ 

char  **list; 
int  directory; 

int  i  =  0; 

switch  (operation)  { 
case  MENU_DI SPLAY: 

directory  =  (int ) menu_get (m,  MENU_CLIENT_DATA) ; 
list  =  get_f ile_names (directory) ; 
while  (*list) 
menu_set  (m, 

MENU_STRING_ITEM,  *list++,  i++, 

0); 

break; 
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case  MENU_DISPLAY_DONE: 

/* 

*  Destroy  old  menu  and  all  its  entries. 

*  Replace  it  with  a  new  menu. 

*/ 

directory  =  (int )  menu_get  (m,  MEND_CLIENT_DATA)  ; 
menu_destroy  (m)  ; 

m  =  menu_create  (MENU_GEN_PROC,  list_files, 
MENU_CLIENT_DATA,  directory, 

0)  ; 

break ; 

case  MENU_N0TIFY: 
case  MENU_NOTIFY_DONE: 
break; 


/*  The  current  or  newly-created  menu  is  returned  */ 
return  m; 


Pull-right  Generate  Procedure  You  can  postpone  the  generation  of  a  pull-right  menu  until  the  user  actually  pulls 

right  by  specifying  a  pull-right  generate  procedure.  A  pull-right  generate  pro¬ 
cedure  has  the  form: 

Menu 

pullright_gen_proc (mi,  operation) 

Menu_item  mi ; 

Menu_generate  operation; 

Note  that  the  puU-ri^t  generate  procedure  is  passed  the  item,  and  returns  the 
menu  to  be  displayed. 

You  can  specify  a  menu  item’s  pull-right  generate  procedure  with  a  call  such  as 

- ^  , 

menu_set (menu_item,  MENU_GEN_PULLRIGHT,  my_pullright_gen ,  0); 

V _ ^ _ _ _ ) 

Alternatively,  you  can  use  the  attributes  menu_GEN_pullright_image  or 
MENU_GEN_PULLRIGHT_ITEM  to  give  a  menu  both  an  item  and  the  item’s 
generate  procedure. 


If  you  want  to  get  die  existing  menu  for  an  item  which  has  a  puUrright  generate 
procedure,  retrieve  die  value  of  die  item,  as  in: 


> 

menu  =  menu  get (item,  MENU_VALUE) ; 

1 

J 
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Notify/ Action  Procedures  When  the  user  selects  a  menu  item  by  releasing  the  mouse  button,  the  menu 

package  calls  back  to  any  notify  procedures  or  action  procedures  you  have 
^  specified.  Notify  procedures  and  action  procedures  have  the  form: 

caddr_t 

notif y_j>roc  (m,  mi) 

Menu  m; 

Menu_item  mi; 

The  most  common  usage  is  to  have  action  procedures  for  the  items  at  the  leaf 
nodes  of  the  walking  menu.  The  general  mechanism  described  below  is  provided 
to  allow  your  procedures  to  be  called  for  non-leaf  nodes  as  well. 

Imagine  a  chain  of  menus  expanded  out.  Lookup  of  the  notify/action  procedures 
starts  with  the  “oldest”  menu,  the  one  passed  to  menu_show  ( ) .  If  it  has  a 
notify  procedure,  that  notify  procedure  is  called,  otherwise  the  default  notify  pro¬ 
cedure,  menu_retur  n_value  ( ) ,  is  called.  Likewise,  for  each  menu  down 
the  chain,  until  the  menu  with  the  selected  item  is  reached.  If  the  selected  item 
has  an  action  procedure,  that  action  procedure  is  called.  If  the  selected  item  is 
not  on  a  leaf  node,  then  action  procedures  for  any  items  farther  down  the  chain 
are  also  called. 

Let’s  see  what  happens  in  the  example  to  the  left  (assume  that  ‘On’  is  the  default 
item  for  the  first  menu): 


Bold  =^ 

1 

On  1 
Off  1 

If  ‘Italic’  was  selected: 

o  no  callback  to  the  first  menu’s  notify  procedure  since  an  item  in  it  is 
selected, 

□  callback  to  the  action  procedure  for  the  ‘Italic’  item, 

□  no  callback  to  the  second  menu’s  notify  procedure  since  it  is  further  down 
the  chain  than  the  selected  item, 

o  callback  to  the  action  procedure  for  the  ‘On’  item. 


If  ‘Off’  was  selected: 

o  callback  to  the  notify  procedure  for  the  first  menu,  since  an  item  in  a  menu 
further  down  the  chain  than  it  is  selected, 

□  no  callback  to  the  action  procedure  for  the  ‘Italic’  item,  since  it  is  above  the 
selected  item  in  the  chain, 

□  no  callback  to  the  second  menu’s  notify  procedure  since  an  item  in  it  is 
selected, 

□  callback  to  the  action  procedure  for  the  ‘Off  item. 

NOTE  If  you  specify  a  notify  procedure,  it  is  your  responsibility  to  propagate  the 

notification  to  any  menus  further  down  in  the  chain.  You  can  do  this  by  calling 
menu_get  (mi ,  MENU_VALUE )  from  your  notify  procedure.  This  gets  the 
value  of  the  selected  menu  item,  and  since  the  value  of  a  puU-right  item  is  the 
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value  of  its  puU-right  menu,  this  will  make  notify/action  procedures  further  down 
the  chain  get  called. 


12.8.  Interaction  with 
Previously  Defined 
SunView  Menus 


Walking  Menus  for  frames  and  tty  subwindows  can  be  customized.  AU  menu 
items  in  these  menus  are  “position-independent”  —  in  other  words  the  menus  do 
not  count  on  a  given  item  having  a  certain  position  or  being  located  in  a  particu¬ 
lar  menu.  This  makes  it  possible  for  you  to  safely  add  new  items  (including 
pull-right  submenus)  to  an  existing  menu. 


NOTE  You  should  not  use  the  client  data  field  of  items  created  by  SunView  packages, 
because  the  packages  have  pre-empted  it  for  their  own  use. 


Using  an  Existing  Menu  as  a 
Pull-right 


The  program  fontjnenu,  listed  in  Appendix  A,  shows  how  you  can  replace  an 
existing  menu  with  your  own  menu  which  has  the  original  menu  as  a  pull-right. 
Making  use  of  several  of  the  examples  given  earlier  in  the  chapter,  it  creates  a 
font  menu  which  allows  the  user  to  select  the  font  family,  point  size,  and  whether 
or  not  the  font  is  bold  or  italic.  Meanwhile,  the  first  item,  labelled  ‘Frame’, 


brings  up  the  original  frame  menu: 

Close 

Fami 1 j 

Move 

Size 

Resize  => 

Bold 

Expose 

Italic 

Hide 

_ 

Redisplay 

Quit 

^  Remember  that  in  order  to  have  these  packages  use  walking  menus  the  user  must  have  enabled  the 
Walking _Menusopdoia  in  SunView  category  of  defaultsedit(l);  in  SunOS  Release  4.0,  this  is  the  default. 
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12.9.  Initial  and  Default  Two  special  menu  items  are  the  default  item  (menu_default_ITEM)  and  the 
Selections  selected  item  (MENU_SELECTED_ITEM).  The  default  item  is  simply  a  dis¬ 

tinguished  item.  The  selected  item  is  the  item  which  was  last  selected. 

Two  attributes  are  provided  to  control  the  behavior  of  a  menu  in  regard  to  its  ini¬ 
tial  selection.  If  menu_initial_SELECTION_selected  is  true,  the 
menu  comes  up  with  its  initial  selection  selected  —  that  is  the  selection  is 
inverted  and  the  cursor  is  positioned  over  it.  If  FALSE,  the  menu  comes  up  with 
the  cursor  “standing  off’  to  the  left  and  no  selection  highlighted.  If 
MENU_INITIAL_SELECTI0N_EXPANDED  is  TRUE,  when  the  menu  comes 
up,  it  automatically  expands  any  puU-rights  which  are  necessary  to  bring  the  ini¬ 
tial  selection  up  on  the  screen. 

Each  menu  also  has  an  initial  selection  (MENU_INITIAL_SELECTI0N)  and  a 
default  selection.  (MENU_DEFAULT__SELECTION). 

The  distinction  between  the  initial  selection  and  the  default  selection  is  subtle. 
Suppose  MENU_INITIAL_SELECTI0N_EXPANDED  was  TRUE,  and  the  ini¬ 
tial  selection  was  an  item  in  a  pull-right.  When  the  menu  comes  up,  it  will  be 
expanded  to  show  the  initial  item  as  selected.  However,  if  the  user  moves  the 
cursor  to  the  left,  backing  out  of  the  pull-right,  and  then  moves  back  to  the  right, 
bringing  the  puU-right  up  again,  the  item  selected  will  be  the  default  selection 
rather  than  the  initial  selection. 

When  the  user  selects  a  pull-right  item  without  bringing  up  the  associated  menu, 
it  is  as  if  he  had  brought  the  puU-right  up  and  selected  the  default  item. 

You  can  set  the  initial  selection  and  the  default  selection  independently  —  either 
can  be  set  to  the  default  item  or  the  selected  item. 
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12.10.  User  Customizable 
Attributes 

Table  12-4 

The  user  can  specify  the  values  of  certain  menu  attributes  in  the  Menu  category 
of  default  sedit(l).  When  a  menu  is  created,  for  attributes  not  explicitly 
specified  by  the  application  program,  the  menu  package  retrieves  the  values  set 
by  the  user  from  the  defaults  database  maintained  by  default  s  edit .  This 
allows  the  user  the  ability  to  tailor,  to  some  extent,  the  appearance  and  behavior 
of  menus  across  different  applications.  For  example,  he  may  want  to  change  the 
type  of  shadow,  or  expand  the  menu  margin,  and  so  on. 

The  attributes  under  default  sedit  control  are  listed  in  the  following  table. 

User  Customizable  Menu  Attributes 

Attribute 

Default 

Description 

MENU_BOXED 

FALSE 

If  TRUE,  a  single-pixel  box  will  be 

^drawn  around  each  menu  item. 

MENU_DEFAULT_SELECTION 

MENU_DEFAULT 

MENU__SELECTED  or  MENUJDEFAULT. 

MENU_F0NT 

screen .b . 12 

Menu’s  font. 

MENU_INITIAL_SELECTION 

MENU_DEFAULT 

me:nu_selected  or  menu_default. 

MENU  INITIAL  SELECTION 

SELECTED 

FALSE 

If  TRUE,  menu  comes  up  with  its  initial 

selection  highlighted.  If  FALSE,  menu  comes 

up  with  the  cursor  "standing  off  to  the  left. 

MENU  INITIAL  SELECTION 

EXPANDED 

TRUE 

If  TRUE,  when  the  menu  pops  up,  it  auto- 

maticaUy  expands  to  select  the  initial  selection. 

MENU  JUMP  AFTER  NO  SELECTION 

FALSE 

If  TRUE,  cursor  jumps  back  to  its 

original  position  after  no  selection  made. 

MENU__JUMP_AFTER_SELECTION 

FALSE 

If  TRUE,  cursor  jumps  back  to  its 

original  position  after  selection  made. 

MENU_MARGIN 

1 

The  margin  around  each  item. 

MENU_LEF  T_MARG IN 

16 

For  each  string  item,  margin  in  addition  to 

menu_margin  on  left 

between  menu’s  border  and  text. 

MENU_PULLRIGHT_DELTA 

9999 

#  of  pixels  the  user  must  move  the  cursor  to 

the  right  to  cause  a  pull-right  menu  to  pop  up. 

MENU_RIGHT_MARGIN 

6 

For  each  string  item,  margin  in  addition  to 

menu_margin  on  right 

between  menu’s  border  and  text. 

MENU_SHADOW 

50%  grey 

Pattern  for  menu’s  shadow. 

O 
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Cursors 


This  chapter  describes  how  to  create  and  manipulate  cursors.^^  A  cursor  is  an 
image  that  tracks  the  mouse  on  the  display.  Each  window  in  SunView  has  its 
own  cursor,  which  you  can  change  widi  the  cursor  package. 

If  it  is  installed  on  your  system,  you  can  run  the  demo 

/usr /demo/ cur  sor__demo  to  see  the  effects  of  various  cursor  attributes. 

The  source  for  this  is  in 

/usr/src/share/sun/suntool/cursor_demo .  c. 

The  definitions  necessary  to  use  cursors  are  found  in  the  include  file 
<sunwindow/win_cur  sor .  h>,  which  is  included  by  default  when  you 
include  the  file  <suntool/ sunview .  h>. 

To  give  you  a  feeling  for  what  you  can  do  with  cursors,  the  following  page  con¬ 
tains  a  list  ofthe  available  cursor  attributes  and  functions.  Many  of  these  are  dis¬ 
cussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to  check).  All  are 
briefly  described  with  their  arguments  in  the  cursor  summary  tables  in  Chapter 
19,  SunView  Interface  Summary: 

□  the  Cursor  Attributes  table  begins  on  page  32 1 ; 

□  the  Cursor  Functions  table  begins  on  page  323. 


8S 


The  cursor  is  called  the  “pointer”  in  user-level  documoitation. 
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Cursor  Attributes 

CURSOR_CROSSHAIR_BORDER_GRAVITY 

CURSOR_OP 

CURSOR_CROSSHAI  R_COLOR 

CURSOR_SHOW_CROSSHAIRS 

CURSOR_CROSSHAIR_GAP 

CURSOR_SHOW_CURSOR 

CURSOR_CROSSHAIR_LENGTH 

CURSOR_SHOW_HORI Z_HAIR 

CURSOR_CROSSHAIR_OP 

CURSOR_SHOW_yERT_HAIR 

CURSOR_CROSSHAIR_THICKNESS 

cursor_vErt_hair_border_gravity 

CDRSOR_FULLSCREEN 

CaRSOR_VERT_HAIR_COLOR 

CURSOR_HORI Z_HAIR_BORDER_GRAVI TY 

CaRSOR_VERT_HAIR_GAP 

CURSOR_HORI Z_HAIR_COLOR 

CDRSOR_VERT_HAIR_LENGTH 

CURSOR_HORI Z_HAIR_GAP 

CURSOR_VERT_HAIR_OP 

CURSOR_HORI Z_HAIR_LENGTH 

CURSOR_VERT_HAIR_THICKNESS 

CURSOR_HORI Z_HAIR_OP 

CURSOR_XHOT 

CURSOR_HORIZ_HAIR_THICKNESS 

CURSOR_IMAGE 

CURSOR^YHOT 

Cursor  Functions 

cursor  copy (src_cursor) 

cursor_get (cursor,  attribute) 

cursor_create (attributes) 

cursor_set (cursor,  attributes) 

cursor  destroy (cursor) 

O 
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The  basic  usage  of  the  cursor  package  is  to  first  create  a  cursor  with 
cur  sor_creat  e  ( ) ,  and  then  use  this  cursor  as  the  value  of  the 
WIN_CURSOR  attribute  in  your  call  to  window_create  ( ) . 

Cursor 

cursor_create (attributes) 

<attribute-list>  attributes; 

Once  you  have  created  a  cursor,  you  can  alter  its  attributes  with 
cursor_set  ( )  and  read  back  its  attributes  with  cursor_get  ( ) : 

void 

cursor_set (cursor,  attributes) 

Cursor  cursor; 

<attribute-list>  a 1 1  r  ibu t  e  s ; 

caddr_t 

cursor_get (cursor,  attribute) 

Cursor  cursor; 

Cursor  attribute  attribute; 


\ _  13.2.  Copying  and 

Destroying  Cursors 


void 

cursor_destroy (cursor) 
Cursor  cursor; 


If  you  want  to  change  the  cursor  of  a  window  that  has  already  been  created,  you 
can  first  get  the  cursor  from  the  window  using  window_get  ( )  of 
WlN_CURSOR,  then  use  cur  sor_set  ( )  to  change  the  cursor,  and  then  use 
window_set  ( )  of  WIN_CURSOR  to  re-attach  the  cursor  to  the  window. 

A  copy  of  an  existing  cursor  can  be  made  with  cursor_copy  ( ) : 

Cursor 

cursor_copy (src_cursor) 

Cursor  src_cursor; 

A  cursor  can  be  destroyed  and  its  resources  freed  with  cur  sor_destroy  { ) : 


13.1.  Creating  and 

Modifying  Cursors 


Example  1 :  Creating  a  Window  A  common  use  for  cursors  might  be  to  create  a  canvas  subwindow  and  have  it 

with  a  Custom  CJursor  use  the  cursor  of  your  choice,  rather  than  the  default  arrow  cursor: 
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short  my_pixrect_data [ ]  =  { 

# include  "filejromjconedit” 

}; 

mpr_static  (my_j)ixrect,  16,  16,  1,  iny_j3ixrect_data)  ; 
Canvas  canvas; 


init_my_canvas  () 
{ 


canvas  =  window_create (frame,  CANVAS, 

WIN_CURSOR,  cursor_create (CURSOR_IMAGE, 


} 


0); 


0)  , 


&my_jpixrect , 


This  example  creates  a  cursor  “on  the  fly”  and  passes  it  into  the 
window_creat  e  ( )  routine  for  use  with  the  canvas.  The  attribute 
CURSOR_iMAGE  is  set  to  the  a  pointer  to  the  pixrect  we  want  to  use  (a  diamond 
or  buUseye,  for  example).  All  of  the  other  cursor  attributes  default  to  the  value 
shown  in  the  attribute  table. 


Example  2:  Changing  the 
Cursor  of  an  Existing  Window 


Suppose  you  have  already  created  a  window  and  you  want  to  change  its  cursor. 
Let’s  say  you  want  to  change  the  drawing  op  to  P  IX_SRC: 
r - ^ 

Cursor  cursor; 

cursor  =  window_get (my_window,  WIN_CURSOR) ; 
cursor_set (cursor,  CURSOR_OP,  PIX_SRC,  0); 
window_set (my_window,  WIN_CORSOR,  cursor,  0) ; 

S _ J 


CAUTION  The  cursor  returned  by  window  get  { )  is  a  pointer  to  a  static  cursor  that 
is  shared  by  all  the  windows  in  your  application.  So,  for  example,  saving  the 
cursor  returned  by  window_get  ( )  and  then  making  other  window  system  calls 
might  result  in  the  saved  cursor  being  overwritten.®^ 

It  is  safe  to  get  the  cursor,  modify  it  with  cur  sor_set  ( )  and  then  put  the  cur¬ 
sor  back.  If  there  is  any  chance  that  the  static  cursor  will  be  overwritten,  you 
should  use  cur  sor_copy  ( )  to  make  a  copy  of  the  cursor,  then  use 
cursor_destr  oy  ( )  when  you  are  done. 

13.3.  Crosshairs  Crosshairs  are  horizontal  and  vertical  lines  whose  intersection  tracks  the  location 

of  the  mouse.  You  can  control  the  appearance  of  both  the  horizontal  and  vertical 
crosshairs  along  with  the  cursor  image.  For  example,  you  can  create  a  cursor  that 
only  shows  the  cursor  image,  or  only  the  horizontal  crosshair,  or  both  the  hor¬ 
izontal  and  vertical  crosshairs  and  the  cursor  image.  By  default  both  the 
crosshairs  are  turned  off  and  only  the  cmsor  image  is  displayed. 


Note  that  this  would  happen  if  one  of  the  routines  you  call  haf^ens  to  call  window  get  ( )  of 
WIN  CURSOR. 
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Example  3:  Turning  on  the  Suppose  you  have  a  canvas  window  in  which  you  want  to  turn  on  both  the  hor- 

Crosshairs  izontal  and  vertical  crosshairs.  This  can  be  done  by  getting  the  cursor  from  the 

window  and  setting  the  CURSOR_SHOW_CROSSHAlRS  attribute: 
- - - 

Cursor  cursor; 

cursor  =  window_get  (iny_canvas,  WIN_CURSOR)  ; 
cursor_set (cursor,  CURSOR_SHOW_CROSSHAIRS,  TRUE,  0); 
window_set {my_canvas,  WIN_CDRSOR,  cursor,  0); 

> _ > 

When  the  crosshairs  are  turned  on,  they  are  displayed  according  to  the  current 
value  of  their  other  attributes  (e.g,  thickness  and  drawing  op). 

13.4.  Some  Cursor  This  section  describes  some  of  the  cursor  attributes  in  more  detail.  Note  that  for 

Attributes  the  crosshair  attributes,  you  can  control  the  individual  crosshairs  as  well  as  both 

crosshairs  by  using  the  appropriate  attribute.  For  example,  you  can  set  the  length 
for  both  crosshairs  with  CURSOR_CROSSHAIR_LENGTH  or  the  length  of  only 
the  horizontal  crosshair  with  CURSOR_HORI  Z_HAIR_LENGTH. 

cuRSOR_iMAGE  The  cursor  image  is  the  memory  pixrect  that  is  drawn  on  the  screen  as  the  mouse 

moves.  Use  the  mpr_static  ( )  macro,  as  shown  in  Example  1,  to  create  the 
memory  pixrect.  The  image  is  represented  as  an  array  of  16  shorts,  each  of 
which  represents  a  16-pixel  wide  scan  line.  The  scan  lines  are  usually  arranged 
in  a  single  column,  yielding  a  16  x  16  pixel  image.  Other  arrangements,  such  as 
32  pixels  wide  x  8  pixels  deep,  are  also  possible.  The  maximum  size  of  a  cursor 
in  SunView  1  is  32  bytes;  the  minimum  width  is  16,  the  width  of  one  scan  line. 

cuRSOR_XHOT  and  cuRSOR_YHOT  The  “hot  spot”  defined  by  ( CURSOR__XHOT,  CURSOR_YHOT )  associates  the 

cursor  image,  which  has  height  and  width,  with  the  mouse  position,  which  is  a 
single  point  on  the  screen.  The  hot  spot  gives  the  mouse  position  an  offset  from 
the  upper-left  comer  of  the  cursor  image.  For  example,  if  the  upper  left  comer  of 
the  cursor  image  is  at  location  (50, 40)  and  the  cursor  hot  spot  has  been  set  to  (8, 
8),  the  reported  mouse  position  will  be  at  (58, 48), 

Most  cursors  have  a  hot  spot  whose  position  is  obvious  from  the  image  shape: 
the  tip  of  an  arrow,  the  center  of  a  buUseye,  the  center  of  a  cross-hair.  Cursors 
can  also  be  used  to  give  status  feedback  —  an  hourglass  to  indicate  that  the  pro¬ 
gram  is  not  responding  to  user  input  is  a  typical  example.  This  type  of  cursor 
should  have  the  hot  spot  located  in  the  middle  of  its  image  so  the  user  has  a 
definite  spot  for  pointing  and  does  not  have  to  guess  where  the  hot  spot  is. 

cuRSOR_op  The  value  given  for  this  attribute  is  the  rasterop  which  will  be  used  to  paint  the 

cursor. P I x_S RC  1  PI x_D S T  is  generally  effective  on  light  backgrounds  — 
in  text,  for  example  —  but  invisible  over  solid  black,  P IX  SRC  "  P IX_DS T 
is  a  reasonable  compromise  over  many  different  backgrounds,  although  it  does 
poorly  over  a  gray  pattern. 


^  Rasterops  are  described  fully  in  the  Pixrect  Reference  Manual. 
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CURS0R_FULLSCREEN  The  cuFSor  crosshaiis  can  be  clipped  to  either  the  cursor’s  window  or  the  entire 

screen.  If  you  want  the  crosshairs  to  extend  past  the  edge  of  the  window,  set 
CURSOR_FULLSCREEN  tO  TRUE. 

cuRsoR_cRossHAiR_LENGTH  If  you  don’t  Want  the  crosshairs  to  cover  the  entire  window  (or  screen),  you  can 

set  the  length  of  both  crosshairs  with  CURSOR_CROSSHAlR_LENGTH.  The 
value  of  this  attribute  is  actually  half  the  total  crosshair  length.  For  example,  if 
you  want  the  crosshairs  to  be  400  pixels  wide  and  high,  set  the 
CURSOR_CROSSHAlR_LENGTH  to  200.  You  can  restore  the  extend-to-edge 
length  by  giving  a  value  of  CURSOR_TO_EDGE  for 
CURSOR_CROSSHAIR_LENGTH. 

cuRSOR_CROssHAiR_BORDER_GRAvrrY  If  the  crosshair  border  gravity  is  enabled,  the  crosshairs  will  "stick"  to  the  edge  of 

the  window  (or  screen).  This  is  only  interesting  if  the 
CURSOR_CROSSHAIR_LENGTH  is  not  settO  CURSOR_TO_EDGE.  With 
border  gravity  turned  on,  each  half  of  each  crosshair  will  be  attached  to  the  edge 
of  the  window.  With  the  cursor  image  displayed,  this  feature  might  be  useful  to 
help  the  user  line  up  the  cursor  to  a  grid  drawn  on  the  edges  of  the  window. 

cuRSOR_CROSSHAiR_GAP  If  yoU  don’t  want  the  halves  of  each  crosshair  to  touch,  you  can  set  the 

CURSOR_CROSSHAlR_GAP  to  the  half-length  of  space  to  leave  between  each 
crosshair  half.  If  you  set  curS0R_CR0SSHAIR_gap  to  CURSOR_to_edge, 
the  crosshairs  will  back  off  to  the  edge  of  the  CURSOR_lMAGE  rectangle. 
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14.1.  Using  Images  Generated  With  iconedit 

14.2.  Modifying  the  Icon’s  Image . 

14.3.  Loading  Icon  Images  At  Run  Time . . 


Icons 


Header  Files 


Summary  Listing  and  Tables 


Icons 


An  icon  is  a  small  (usually  64  by  64  pixel)  picture  representing  a  base  frame  in 
its  closed  state.  The  icon  is  typically  a  picture  indicating  the  ftmction  of  the 
underlying  application. 

The  definitions  necessary  to  use  icons  are  found  in  the  file 
<suntool/icon .  h>,  which  is  included  by  default  when  you  include  the  file 
<suntool/sunview .h>. 

To  give  you  a  feeling  for  what  you  can  do  with  icons,  the  following  page  lists  the 
available  icon  attributes,  functions  and  macros.  Many  of  these  are  discussed  in 
the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to  check).  AU  are  briefly 
described  with  their  arguments  in  the  menu  summary  tables  in  Chapter  19,  Sun- 
View  Interface  Summary: 

□  the  Icon  Attributes  table  begins  on  page  32 8 ; 

□  the  Icon  Functions  and  Macros  table  begins  on  page  329. 
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Icon  Attributes 

ICON_FONT 

ICON_IMAGE_RECT 

ICON_WIDTH 

ICON_HEIGHT 

ICON_LABEL 

ICON_IMAGE 

I CON_LABEL_RECT 

Jeon  Functions  and  Attributes 

icon__create  (attributes)- 

icon_set (icon,  attributes) 

icon  destroy (icon) 

DEF INE_lCON_FROM_IMAGE ( name ,  image ) 

icon_get (icon,  attribute) 

14.1.  Using  Images  You  can  create  and  edit  images  easily  using  the  program  iconedit(l).  The 

Generated  With  output  of  iconedit  is  a  file  containing  an  array  of  shorts  representing  the 

iconedit  image.  In  order  to  use  the  image  in  a  program,  you  must  first  define  a  static 

memory  pixrect  containing  this  data.  The  mpr_static  { )  macro  is  provided 
for  this  purpose. 

The  first  argument  to  mpr_static  ( )  is  the  name  of  the  pixrect  to  be  defined. 
Next  come  the  width,  height  and  depth  of  the  image,  typically  64,  64  and  1.  The 
last  argument  is  the  array  of  shorts  containing  the  bit  pattern  of  the  icon  image. 
For  example: 

static  short  icon_iinage  []  =  { 
tinclude  "file_generated_by_iconedit" 

}; 

nipr_static  (iconjiixrect ,  64,  64,  1,  icon_iinage) ; 
s _ > 


The  statically  defined  image  is  passed  in  to  icon_create  ( )  at  run  time: 

- ^ 

my_icon  =  icon_create (ICON_IMAGE,  &iGon_j)ixrect ,  0); 

k _ _ _ > 


Once  you  have  created  an  icon,  you  can  retrieve  and  modify  its  attributes  with 
icon_get  ( )  and  icon_set  { ) ,  and  destroy  it  with  icon_destr  oy  { ) . 

Instead  of  creating  the  icon  dynamically  with  icon_create  { ) ,  you  can  use 
the  DEFINE__IC0N_FR0M_IMAGE  ( )  macro  to  generate  a  static  icon.^^ 

( - 1 

static  short  icon_image [ ]  =  { 

#include  "file_generated_by_iconedit" 

}; 

DEFINE_ICON_FROM_IMAGE (icon,  icon_image> ; 

. _ ^ ^ _ > 

This  macro  statically  allocates  a  structure  representing  an  icon.  Note  that  you 


**  The  structure  generated  is  actually  an  extern. 
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must  pass  the  address  of  this  structure  —  &  icon  in  the  example  above  —  into 
icon_get  { ) ,  icon_set  ( ) ,  and  icon_destroY  ( ) . 

WARNING  The  DEFINE_IC0N_FR0M_IMAGE  ( )  macro  may  not  be  supported  in  future 
releases.  We  reccommend  that  you  use  ±con_ci:eate{)  instead. 


14.2.  Modifying  the  Icon’s  It  is  often  useful  to  change  the  icon’s  image  dynamically,  rather  than  simply 

Image  using  the  icon  as  a  static  placeholder.  When  mailtool  receives  new  mail,  for 

example,  it  lets  the  user  know  by  modifying  its  icon  to  show  a  letter  arrived  in 
the  mailbox,  clocktool  uses  its  icon  to  represent  a  moving  clock  face. 

The  steps  to  follow  in  modifying  an  icon’s  image  are: 

□  get  the  frame’s  icon  (attribute  FRAME_lCON); 

□  get  the  icon’s  pixrect  (attribute  IC0N_IMAGE); 

□  modify  the  pixrect  as  desired,  or  substitute  a  new  pixrect; 
o  give  the  pixrect  with  the  new  image  back  to  the  icon; 

□  give  the  new  icon  back  to  the  frame. 

For  example: 


modify_icon (frame) ; 

Frame  frame; 

Icon  icon; 

Pixrect  *pr; 

icon  =  (Icon)  window_get (frame,  FRAME_ICON) ; 
pr  =  (Pixrect  *)  icon_get (icon,  ICON_IMAGE) ; 

(modify  prj 

icon_set (icon,  ICON_IMAGE,  pr,  0); 
window_set (frame,  FRAME_ICON,  icon,  0); 

1 


14.3.  Loading  Icon  Images  Often  it  is  sufficient  to  define  the  image  for  a  program’s  icon  at  compile  time. 
At  Run  Time  with  inpr_stat  ic  ( ) .  However,  you  may  want  to  allow  the  user  to  create  his 

own  icon  images,  and  give  the  names  of  the  files  containing  the  images  to  your 
program  as  command-line  arguments.  Then  you  can  load  the  images  from  the 
files  the  user  has  specified.  Routines  to  load  icon  images  from  files  at  run  time 
are  described  in  Chapter  1 1  of  the  SunView  1  System  Programmer’s  Guide. 
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Undoing  a  Scroll . 
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Scrollbars 


The  canvas,  text  and  panel  subwindows  have  been  designed  to  work  with 
scrollbars.  The  text  subwindow  automatically  creates  its  own  vertical  scrollbar. 
For  canvases  and  panels,  it  is  your  responsibility  to  create  the  scrollbar  and  pass 
it  in  with  the  attributes  WIN_VERTICAL_SCR0LLBAR  or 
WIN_HORI ZONTAL_SCROLLBAR. 

Section  15.2,  Scrollbar  User  Interface,  describes  how  the  user  interacts  with 
scrollbars.  Basic  scrollbar  usage  is  covered  in  Section  15.3,  Creating,  Destroy¬ 
ing  and  Modifying  Scrollbars,  and  programmatic  scrolling  is  covered  in  Section 
'  15.4,  Programmatic  Scrolling. 

You  may  want  to  use  scrollbars  in  an  application  not  based  on  canvases,  text 
subwindows  or  panels,  in  which  case  you  must  manage  the  interaction  with  the 
scrollbar  directly.  For  an  explanation  of  how  to  do  this,  see  the  Scrollbars 
chapter  in  the  SunView  1  System  Programmer’s  Guide. 

Header  Files  The  definitions  necessary  to  use  scrollbars  are  found  in  the  header  file 

<suntool/scrollbar .h> 

Summary  Listing  and  Tables  To  give  you  a  feeling  for  what  you  can  do  with  scrollbars,  the  following  page 

contains  a  list  of  the  available  scrollbar  attributes,  functions  and  macros.  Many 
of  these  are  discussed  in  the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to 
check).  All  are  briefly  described  with  their  arguments  in  the  scrollbar  summary 
tables  in  Chapter  19,  SunView  Interface  Summary: 

□  the  Scrollbar  Attributes  table  begins  on  page  362; 

□  the  Scrollbar  Functions  table  begins  on  page  365. 
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Scrollbar  Attributes 


SCROLL_ABSOLUTE_CURSOR 

SCROLL_ACT I VE_CURSOR 

SCROLL_ADVANCED_MODE 

SCROLL_BACKWARD_CURSOR 

SCROLL_BAR_COLOR 

SCROLL_BAR_DI SPLAY_LEVEL 

SCROLL_BORDER 

SCROLL_BDBBLE_COLOR 

SCROLL_BUBBLE_D I SPLAY_LEVEL 

SCROLL_BUBBLE_MARGIN 

SCROLL_DIRECTION 

SCROLL_END_POINT_AREA 

SCROLL_FORWARD_CURSOR 

SCROLL_GAP 

SCROLL_HEIGHT 

SCROLL_LAST_VIEW_START 

SCROLL_LEFT 

SCROLL_LINE_HEI GHT 

SCROLL_M2yRGIN 

SCROLL  MARK 


SCROLL_NOTIFY_CLIENT 

SCROLL_NORMALI ZE 

SCROLL_OBJECT 

SCROLL_OBJECT_LENGTH 

SCROLL_PAGE_BUTTONS 

SCROLL_PAGE_BUTTON_LENGTH 

SCROLL_PAINT_BUTTONS_PROC 

SCROLL_PIXWIN 

SCROLL_P  LACEMENT 

SCROLL_RECT 

SCROLL_REPEAT_TIME 

SCROLL_REQUEST_MOTION 

SCROLL_REQUEST_OFFSET 

SCROLL_THI CKNE  SS 

SCROLL_TO_GRID 

SCROLL_TOP 

SCROLL_VIEW_LENGTH 

SCROLL_VIEW_START 

SCROLL  WIDTH 


Scrollbar  Functions  and  Macros 


scrollbar_create (attributes) 
scrollbar_destroy (scrollbar) 
scrollbar_get (scrollbar,  attribute) 
scrollbar_set (scrollbar,  attributes) 
scrollbar  scroll  to (scrollbar,  new_view_start) 


scrollbar_paint (scrollbar) 
scrollbar_j3aint_clear  (scrollbar) 
scrollbar_clear_bubble (scrollbar) 
scrollbar_paint_bubble (scrollbar) 
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15.1.  Scrolling  Model  Scrollbars  aUow  the  user  to  control  which  portion  of  an  object  is  visible  when  the 

object  is  larger  than  the  window  it  is  displayed  in.  Within  the  scroUbar  is  a 
darker  area  called  the  bubble.  The  size  and  position  of  the  bubble  within  the  bar 
tell  the  user  where  he  is  in  the  object  and  how  much  of  the  object  is  visible.  By 
moving  the  bubble  within  the  bar,  the  user  brings  different  portions  of  the  object 
into  view. 

The  length  of  the  object,  the  length  of  the  visible  portion  of  the  object,  and  the 
offset  of  the  visible  portion  within  the  object  are  given  by  the  attributes 
SCROLL_OBJECT_LENGTH,  SCROLL_VIEW_LENGTH,  and 
S CROLL_viEW_START.  The  relationship  between  these  three  view-space 
metrics  is  shown  in  the  figure  on  the  next  page. 
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Figure  15-1  Scrolling  Model 


Figure  15-1  shows  a  two-page  document  being  viewed  within  a  window  roughly 
half  the  size  of  the  document.  The  three  view-space  attributes 

SCROLL_OBJECT_LENGTH,  SCROLL_VIEW_LENGTH,  and 
SCROLL  VIEW  START  are  shown  superimposed  on  the  document.  Note  the 
relative  sl^e  and  position  of  the  bubble  within  the  scroUbar  —  it  is  roughly  half 
the  size  of  the  window  and  positioned  near  the  bottom. 
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15.2.  Scrollbar  User 
Interface 

Types  of  Scrolling  Motion  The  default  scrollbar  is  vertical,  with  page  buttons  at  the  top  and  bottom.  To 

scroll,  the  user  moves  the  cursor  into  the  scrollbar  (either  the  bar  itself  or  one  of 
the  page  buttons)  and  clicks  one  of  the  mouse  buttons.  The  following  table 
describes  the  available  scrolling  actions  and  how  they  are  generated: 

Table  15-1  Scrolling  Motions 


Mouse  Button 

Cursor  Location 

Scrolling  Action 

LEFT 

page  button 

Line  forwards 

RIGHT 

page  button 

Line  backward 

MIDDLE 

page  button 

Page  forward 

MIDDLE  (shifted) 

page  button 

Page  backward 

LEFT 

bar 

Line  opposite  cursor  goes  to  top 

RIGHT 

bar 

Top  line  comes  to  cursor 

LEFT  (shifted) 

bar 

Bottom  line  comes  to  cursor 

RIGHT  (shifted) 

bar 

Line  opposite  cursor  goes  to  bottom 

MIDDLE 

bar 

The  line  whose  offset  into  the 
scrolling  object  approximates  that 
of  the  cursor  into  the  scrollbar  is 
positioned  at  top  (“thumbing”). 

Holding  the  button  down  within  the  scrollbar  causes  the  cursor  to  change,  pre¬ 
viewing  the  scrolling  action  for  that  button.  Releasing  the  button  causes  the 
scrolling  action  to  be  performed,  or,  if  the  user  holds  down  the  mouse  button,  the 
scrolling  motion  will  start  in  repeating  mode. 

Undoing  a  Scroll  [  Shift  1-MIDDLE  mouse  button  positions  the  viewing  window  to  the  most  recent 

position  which  was  left  by  an  absolute  motion  (thumbing  or  undoing).  The  undo¬ 
ing  position  is  initialized  to  the  beginning  of  the  scrollable  object. 


Asun 

Xr  microsystems 


Revision  A,  of  May  9,  1988 


272  SunView  1  Programmer’s  Guide 


15.3.  Creating,  Destroying  Scrollbars  are  created  and  destroyed  with  scrollbar_create  ( )  and 

and  Modifying  s  cr  ollbar_destr  oy  ( ) .  To  take  the  simplest  possible  example,  you  get  a 

Scrollbars  default  scrollbar  (vertical,  on  the  left  edge  of  the  subwindow,  etc.)  by  calling: 


/■ 

Scrollbar  bar; 

bar  =  scrollbar_create (0) ; 

v - — - 

J 

You  would  destroy  the  scroUbar  with  the  call: 

<  —  > 
scrollbar_destroy (bar) ; 

^ - — - - - 


The  appearance  and  behavior  of  a  given  scrollbar  is  detennined  by  the  values  of 
its  attributes.  Here’s  an  example  of  a  non-default  scroUbar: 


r~ 

bar  1  =  scrollbar_create ( 

SCROLL  PLACEMENT, 

SCROLL_EAST, 

SCROLL  BUBBLE  COLOR, 

SCROLL_BLACK, 

SCROLL  BAR  DISPLAY  LEVEL, 

SCROLL_ACTIVE, 

SCROLL  BUBBLE  DISPLAY  LEVEL, 

SCROLL_ACTIVE, 

SCROLL  DIRECTION, 

SCROLL_VERTICAL, 

SCROLLJTHI CKNESS , 

20, 

SCROLL_BDBBLE_MARGIN , 

4, 

0)  , 

1 

J 

In  the  above  caU,  setting  SCROLL_PLACEMENT  to  SCROLL_EAST  wiU  cause 
the  scroUbar  to  appear  on  the  right  edge  of  the  subwindow.  The  scroUbar  wiU  be 
20  pixels  wide  wiUi  a  black  bubble  4  pixels  from  each  edge  of  the  bar.  The  bar 
and  bubble  wiU  be  shown  only  when  the  cursor  is  in  the  scroUbar. 

You  can  modify  and  retrieve  the  attributes  of  a  scroUbar  with  the  two  routines: 

scrollbar_set (scrollbar,  attributes) 

Scrollbar  scrollbar; 

<attribute-lisf>  attributes; 

caddr_t 

scrollbar_get (scrollbar,  attribute) 

Scrollbar  scrollbar; 

Scrollbar_attribute  attributes; 

If  the  scrollbar  parameter  is  NULL,  scrollbar_get  ()  returns  0. 

SCROLL_RECT,  SCROLL_T HICKNESS,  SCROLL_HEIGHT  and 
SCROLL_wiDTH  do  not  have  valid  values  until  the  scroUbar  is  passed  into  the 
subwindow.  As  a  work-around  for  this  problem,  the  special  symbol 
SCROLLBAR  has  been  provided.  You  can  determine  the  default  thickness  of  a 
scroUbar  before  it  has  been  attached  to  a  subwindow  with  the  caU: 
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thickness  =  (int)  scrollbar_get (SCROLLBAR,  SCROLL_THICKNESS)  ; 
s _ _ _ > 

This  convention  is  currently  only  implemented  for  SCROLL_THICKNESS. 

If  you  set  the  SCROLL_THlCKNES  S  attribute  then  you  must  also  set  the 
SCROLL_DIRECTlON  of  the  scroUbar,  since  the  dimension  of  the  scrollbar  that 
is  altered  by  SCROLL_thickness  depends  on  the  orientation  of  the  scrollbar. 

The  figures  on  the  next  page  show  some  of  the  attributes  controlling  the  visual 
appearance  of  a  scroUbar.^^  Figure  15-2  illustrates  the  attributes  that  control  the 
scrollbar  appearance.  Figure  15-3  illustrates  the  attributes  that  control  the 
scrollbar  placement 


Fora  complete  list 
Interface  Summary. 


of  the  scrollbar  attributes  see  the  Scrollbar  Attributes  table  in  Chapter  19,  SimView 
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Figure  15-2 


Figure  15-3 


Attributes  Controlling  Scrollbar  Appearance 


Page  Button  Attributes 


SCROLL_PAGE_BUTTONS:  TRUE  or  FALSE 
SCROLL_PAGE_BUTTON_LENGTH 


Bubble  Attributes: 


SCROLL_BUBBLE_MARGIN 

SCR0LL_BUBBLE_C0L0R 


SCROLL_BLACK 

SCROLL_GREV 


Scrollbar  Placement  Attributes 


SCROLL_DIRECTION : 

SCROLL  VERTICAL  SCROLL  HORIZONTAL 
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15.4.  Programmatic 
Scrolling 


To  scroll  to  a  given  location  from  your  program,  caU: 

scrollbar__scroll_to  (scrollbar,  new_view_start ) 

Scrollbar  scrollbar; 
long  new_view_start ; 

This  routine  saves  the  current  value  of  SCROLL_VIEW_START  as 
SCROLL_LAST_VIEW_START,  sets  SCROLL_VIEW_START  tO  the  value 
passed  in  as  new_view_start,  and  posts  a  scroll  event  to  the  scrollbar’s 
client  (i.e.  the  canvas,  panel  or  text  subwindow)  using  the  Notifier.  This  has  the 
same  effect  as  if  the  user  had  requested  a  scroll  to  new_view_start. 
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The  Selection  Service 


16.1.  Getting  the  Primary  Selection 

16.2.  Setting  the  Primary  Selection 


b  4  ,  J’  •  I  I  -  •  *  I*  T  •*  -  '  c ,  *  •  ^  ^  «  •  C  •  s^'‘  »  '  ♦ 


••  ••  //a 


16 


X«X  •vHWU*  >  ❖  X**  i**  -{f  X-*  vXsVfVX 


The  Selection  Service 


The  Selection  Service  provides  for  flexible  communication  among  window  appli¬ 
cations.  You  can  use  the  Selection  Service  to  query  and  manipulate  the  selec¬ 
tions  the  user  has  made. 

This  chapter  gives  only  the  simplest  example  of  using  the  Selection  Service,  To 
find  out  more  about  the  Selection  Service  and  the  other  functionality  it  provides, 
refer  to  Chapter  9  of  the  SunView  1  System  Programmer’ s  Guide. 

The  definitions  necessary  to  use  the  Selection  Service  are  found  in  the  include 
file  <suntool/seln  .h>. 
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16.1.  Getting  the  Primary  The  primary  selection  is  the  selection  made  by  the  user  without  holding  down 

Selection  any  of  the  function  keys,  and  is  indicated  with  reverse-video  highlighting  on  the 

screen. 

The  routine  below  is  taken  from  the  program  filer,  listed  in  Appendix  A.  It 
retrieves  the  primary  selection  by  first  asking  the  Selection  Service  which  win¬ 
dow  has  the  primary  selection,  then  asking  that  window  for  the  characters  that 
are  in  the  selection,  saving  them  in  a  static  buffer,  and  returning  a  pointer  to  that 
buffer; 


♦define  <suntool/seln.h> 

♦define  MAX_FILENAME_LEN  256 
char  * 

get_selection () 

{ 

static  char  filename  [M2e{_FILENAME_LEN]  ; 

Seln_holder  holder; 

Seln_request  *buffer; 

holder  =  seln_inquire (SELN_PRIMARY) ; 

buffer  =  seln_ask (Sholder,  SELN_REQ_CONTENTS_ASCII,  0,  0) ; 
strncpy (filename, 

buffer->data  +  sizeof (Seln_at tribute) , 
MAX_FILENAME_LEN) ; 

return  (filename) ; 

} 

V. - — _ _ . 

This  example  has  been  kept  simple  by  removing  error  checking.  The  code  relies 
on  the  fact  that  if  there  is  no  primary  selection,  or  the  Selection  Service  process  is 
not  running,  or  the  holder  of  the  primary  selection  failed  to  returned  the  selection 
string,  then  the  buffer  returned  by  seln_ask  ( )  will  have  an  empty  string  for 
the  selection  characters. 

The  routine  also  assumes  that  the  selection  will  be  no  more  than  256  characters 
long.  seln_ask  ( )  wiU  handle  selections  of  up  to  about  2000  characters.  To 
find  out  how  to  handle  arbitrarily  large  selections,  or  selections  other  than  the  pri¬ 
mary  selection,  refer  to  the  SunView  1  System  Programmer’s  Guide. 

16.2.  Setting  the  Primary  For  an  example  of  a  program  which  sets,  and  responds  to  queries  about,  the 

Selection  selection,  see  seln  demo,  in  Chapter  9  of  the  SunView  1  System  Programmer’s 

Guide. 
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The  Notifier 


The  Notifier  is  a  general-purpose  mechanism  for  distributing  events  to  a  collec¬ 
tion  of  clients  within  a  process.  It  detects  events  in  which  its  clients  have 
expressed  an  interest,  and  dispatches  these  events  to  the  proper  clients,  queuing 
client  processing  so  that  clients  respond  to  events  in  a  predictable  order. 

An  overview  of  the  notification-based  model  is  given  in  Chapter  2,  The  SunView 
Model 

To  encourage  the  porting  of  existing  applications,  the  Notifier  has  provisions  to 
allow  programs  to  run  in  the  Notifier  environment  without  inverting  their  control 
structure.  See  Section  17.6,  Porting  Programs  to  SunView. 

Header  Files  The  definitions  for  the  Notifier  are  contained  in  the  file 

<sunwindow/ notify .  h>,  which  will  be  included  indirectly  when  you 
include  <suntool/sunview .  h>.^® 

Related  Documentation  This  chapter  will  suffice  for  the  majority  of  SunView  applications.  See  the 

chapters  titled  Advanced  Notifier  Usage  and  The  Agent  and  Tiles  in  the  Sun¬ 
View  1  System  Programmer’s  Guide  for  more  information  on  the  Notifier  and 
SunView’s  usage  of  it.  When  looking  up  Notifier-related  information,  look  first 
in  the  index  to  this  book,  then  in  the  index  to  the  SunView  1  System 
Programmer’s  Guide. 

Summary  Listing  and  Table  To  give  you  a  feeling  for  what  you  can  do  with  the  Notifier,  the  following  page 

contains  a  list  of  the  available  Notifier  fimctions.  Many  of  these  are  discussed  in 
the  rest  of  this  chapter  and  elsewhere  (use  the  Index  to  check).  All  are  briefly 
described  with  their  arguments  in  the  Notifier  Functions  table  beginning  on  page 
343  in  Chapter  19,  SunView  Interface  Summary. 


50  For  those  programmers  utilizmg  the  Notifier  outside  of  SunView  (a  perfectly  reasonable  thing  to  do),  the 
code  that  implements  the  Notifier  is  found  in  /usr/lib/libsunwindow.a. 
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_ _ Notifier  Functions _ 

notifyMaefault_wait3 (client,  pid,  status,  rusage) 
notify_dispatch ( ) 
notify_do_dispatch ( ) 

notify_interpose_destroy_func (client,  destroy_func) 
notify_interpose_event_func (client,  event_func,  type) 
notify_itimer_value (client,  which,  value) 
notify_next_destroy_func (client,  status) 
notif y_no_dispatch ( ) 
notify_perror (s) 

notify_set_destroy__func  (client,  destroy_func) 

not ify_set_exception_func  (client,  except ion__func,  fd) 

not if y_set_input_func (client,  input_func,  fd) 

notify_set_itimer_func (client,  itimer_func,  which,  value,  ovalue) 
notify_set_signal_func (client,  signal_func,  signal,  when) 
notif y_start  () 
notify_stop () 

not if y_set_output_func (client ,  output_func,  fd) 
notify_set_wait3__func  (client,  wait3_func,  pid) 
notify_veto_destroy (client) 


o 


i 
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17.1.  When  to  Use  the 
Notifier 

Since  the  Notifier  is  used  by  the  SunView  libraries,  any  program  that  uses  Sun- 
View  implicitly  uses  the  Notifier.  You  will  have  to  use  the  Notifier  explicitly  if 
you  want  to  do  any  of  the  following: 

□  Catch  signals,  e.g.,  SIGCONT, 

□  Notice  state  changes  in  processes  that  your  process  has  spawned,  e.g.,  a  child 
process  has  died. 

□  Read  and  write  through  file  descriptors,  e.g.,  using  pipes. 

□  Receive  notification  of  the  expiration  of  an  interval  timer,  e.g.,  so  that  you 
can  provide  some  blinking  user  feedback. 

□  Extend,  modify  or  monitor  SunView  Notifier  clients,  e.g.,  noticing  when  a 
frame  is  opened,  closed  or  about  to  be  destroyed. 

□  Use  a  non-notification-based  control  structure  while  running  under  Sun¬ 
View,  e.g.,  porting  programs  to  SunView. 

17.2.  Restrictions 

The  Notifier  imposes  some  restrictions  on  its  clients  which  designers  should  be 
aware  of  when  developing  software  to  work  in  the  Notifier  environment.  These 
restrictions  exist  so  that  the  application  and  the  Notifier  don’t  interfere  with  each 
other.  More  precisely,  since  the  Notifier  is  multiplexing  access  to  user  process 
resources,  the  application  needs  to  respect  this  effort  so  as  not  to  violate  the  shar¬ 
ing  mechanism. 

Don’t  Call. . . 

Assuming  an  environment  with  multiple  clients  with  an  unknown  notifier  usage 
pattern,  you  should  not  use  any  of  the  following  system  calls  or  C  library  rou- 
tines:^^ 

signal(3) 

The  Notifier  is  catching  signals  on  the  behalf  of  its  clients.  If  you  set  up  your 
own  signal  handler  over  the  one  that  the  Notifier  has  set  up  then  the  Notifier  will 
never  notice  the  signal. 

sigvec(2) 

The  same  applies  for  sigvec(2)  as  does  for  signal(3),  above. 

setitimer(2) 

The  Notifier  is  managing  two  of  the  process’s  interval  timers  on  the  behalf  of  its 
many  clients.  If  you  access  an  interval  timer  directly,  the  Notifier  could  miss  a 
timeout.  Use  notif  y_set_itimer_func  ( )  instead  of  set  it  inter  (2). 

alarm(3) 

Because  alarm(3)  sets  the  process’s  interval  timer  directly,  the  same  applies  for 
alarm(3)  as  does  for  setitimer(2),  above. 

getitimer(2) 

When  using  a  notifier-managed  interval  timer,  you  should  call 

notif  y_itimer_value  ( )  to  get  its  current  status.  Otherwise,  you  can  get 

inaccurate  results. 

wait  3  (2) 

The  Notifier  notices  child  process  state  changes  on  behalf  of  its  clients.  If  you  do 
your  own  wait  3(2),  then  the  notifier  may  never  notice  the  change  in  a  child 

A  future  release  may  provide  modified  versions  of  some  of  these  forbidden  routines  that  will  allow  their 
use  without  restriction.  However,  the  restricticnis  described  in  Don't  Catch. . below,  will  continue  to  be 
germane.  A  signal  ( )  Replacement  for  Notifier  Compatibility,  in  Section  17.4,  provides  a  code  patch  for 
programs  that  catch  signals. 
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wait  (2) 

ioctl(2)  (...,  FIONBIO, ...) 

ioctl(2)  (...,  FIOASYNC,  .„) 


system(3) 


process  or  you  may  get  a  change  of  state  for  a  child  process  in  which  you  have  no 
interest.  Use  not  if  y_set_wait3_f  unc  ( )  instead  of  wait  3(2), 

The  same  applies  for  wait (2)  as  does  for  wait  3(2),  above. 

This  call  sets  the  blocking  status  of  a  file  descriptor.  The  Notifier  needs  to  know 
the  blocking  status  of  a  file  descriptor  in  order  to  determine  if  there  is  activity  on 
it.  f  cntl(2)  has  an  analogous  request  that  should  be  used  instead  of  ioctl(2). 

This  caU  controls  a  file  descriptor’s  asynchronous  io  mode  setting.  The  Notifier 
needs  to  know  this  mode  in  order  to  determine  if  there  is  activity  on  it 
font  1(2)  has  an  analogous  request  that  should  be  used  instead  of  ioct  1(2). 

In  the  SunOS,  this  function  calls  signal(3)  and  wait(2).  Hence  you  should 
avoid  using  this  for  the  reasons  mentioned  above.  Calls  to  sys  tem(3)  should  be 
replaced  with  something  like  the  following. 

f  ' 

if  ( (pid  =  vforkO)  ==  0)  { 

(void)  execl("/bin/sh",  ”sh",  "-c”,  str,  (char  *)0); 
_exit  (127) ; 

} 

notify_set_wait3_func  (me,  my_handler,  pid); 

^ _ _ _ ^ 


Don’t  Catch. . .  Clients  should  not  have  to  catch  any  of  the  following  signals.  If  you  are,  then 

you  are  probably  also  making  one  of  the  forbidden  calls  described  above.  You 
might  also  be  utilizing  the  Notifier  inappropriately  if  you  think  that  you  have  to 
catch  any  of  these  signals.  The  Notifier  catches  these  signals  itself  under  a 
variety  of  circumstances; 

S I GALRM  Caught  by  the  Notifier’s  interval  timer  manager.  Use 

notif  y_set_itiiner_func  ( )  instead. 

s IGVTALRM  The  same  applies  for  SIGVTALRM  as  does  for  S igalrm  above. 


S I GTERM  Caught  by  the  Notifier  so  that  it  can  teU  its  clients  that  the  process  is  going  away. 

Use  notif  y_set_destroy_f  unc  ( )  if  that  is  why  you  are  catching 
SIGTERM. 


S I GCHLD  Caught  by  the  Notifier  so  that  it  can  do  child  process  management.  Use 

notif y_set_wait3_f unc  ( )  instead. 

SIGIO  Caught  by  the  Notifier  so  that  it  can  manage  its  file  descriptors  that  are  running  in 

asynchronous  io  mode.  Use  notif  y_set_input_f  unc  ( )  or 
not  if  y_set_output_f  unc  ( )  if  you  want  to  know  when  there  is  activity 
on  your  file  descriptor. 

S IGURG  Caught  by  the  Notifier  so  that  it  can  dispatch  exception  activity  on  a  file  descrip¬ 
tor  to  its  clients.  Use  notif  y_set_exception_f  unc  { >  if  you  are  looking 
for  out-of-band  communications  when  using  a  socket. 


^  Do  not  use  a  NULL  client  handle  when  you  use  notify_set_input  func  ( )  or  the  Notifier  will  go 
into  an  infinite  loop. 
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If  you  think  you  have  to  catch  one  of  these  signals,  then  be  sure  to  use 
notif  y_set_signal_f unc  ( ) . 


17,3.  Overview 

How  the  Notifier  Works  Before  it  can  receive  events,  a  client  must  advise  the  Notifier  of  the  types  of 

events  in  which  it  is  interested.  It  does  this  by  registering  an  event  handler  func¬ 
tion  (which  it  must  supply)  for  each  type  of  event  in  which  it  is  interested.  When 
an  event  occurs,  the  Notifier  calls  the  event  handler  appropriate  to  the  type  of 
event 

Figure  17-1  shows  an  overview  of  how  the  notification  mechanism  works. 


Figure  17-1  Overview  of  Notification 


—  Client  registers  event  proc  at  initialization  time 
- Notifier  calls  back  to  client  when  event  received 

Client  Handles  The  Notifier  uses  a  client  handle  as  the  unique  identifier  for  a  given  client  The 

Notifier,  without  interpreting  the  client  handle  in  any  way,  uses  it  to  associate 
each  event  with  the  event  handler  for  a  given  client. 

The  only  requirement  for  a  client  handle  is  that  it  must  be  unique  (within  a  pro¬ 
cess).  Since  a  program  text  address  or  the  address  of  an  allocated  data  block  are 
guaranteed  to  be  imique,  they  can  be  used.  Since  stack  addresses  are  not  in  gen¬ 
eral  guaranteed  to  be  unique  they  should  not  be  used.  Internally,  SunView  uses 
the  object  handles  returned  from  wind.ow_create  ( )  as  notifier  client  handles. 

Types  of  Interaction  Client  interaction  with  the  Notifier  falls  into  the  following  functional  areas: 

□  Event  handling  —  A  client  may  receive  events  and  respond  to  them  via 
event  handlers.  Event  handlers  do  the  bulk  of  the  work  in  the  Notifier 
environment.  The  various  types  of  events  are  in  Section  17.4,  Event  Han¬ 
dling. 

□  Interposition  —  A  client  may  request  that  the  Notifier  install  a  special  type 
of  event  handler  (supplied  by  the  client)  to  be  inserted  (or  interposed)  ahead 
of  the  current  event  handler  for  a  given  type  of  event  and  client.  This  allows 
clients  to  screen  incoming  events  and  redirect  them,  and  to  monitor  and 
change  the  status  of  other  clients.  Examples  of  interposition  may  be  found 
below  under  Monitoring  a  Frame’s  State. 
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□  Notifier  control  —  A  client  may  exercise  control  over  when  dispatching  of 
events  occurs.  See  Section  17.6,  Porting  Programs  to  SunView. 

17.4.  Event  Handling  This  section  describes  how  to  be  notified  of  UNIX-related  events  and  notifier  sup¬ 

ported  destroy  events  (see  Chapter  6,  Handling  Input,  for  a  description  of 
SunView-defined  events).  UNIX  events  are  low-level  occurrences  that  are  mean¬ 
ingful  at  the  level  of  the  operating  system.  These  include  signals  (software  inter¬ 
rupts),  input  pending  on  a  file  descriptor,  output  completed  on  a  file  descriptor, 
tasks  associated  with  managing  child  processes,  and  tasks  associated  with 
managing  interval  timers. 

A  client  establishes  an  interest  in  a  certain  type  of  event  by  registering  an  event 
handler  procedure  to  respond  to  it.  The  event  handler  for  a  given  type  of  event 
has  a  mandatory  calling  sequence,  as  described  below.  All  event  handlers  return 
a  value  of  either  notify_done  or  notify_IGNORED  depending  on  whether 
the  event  was  acted  on  in  some  way  or  failed  to  provoke  any  action,  respectively. 

When  registering  an  event  handler,  the  registration  procedure  returns  a  pointer  to 
the  function  that  was  in  place  previous  to  the  current  call.  On  initialization,  the 
Notifier  sets  up  its  internal  tables  by  registering  “dummy”  functions  as  place¬ 
holders.  These  dummy  functions  are  no-op  functions  with  no  harmful  side- 
effects.  The  first  time  a  client  registers  a  given  type  of  event  handler,  it  will 
receive  a  pointer  to  a  “dummy”  function. 

The  following  sections  describe  common  usages  of  various  types  of  events. 

Child  Process  Control  Events  Let’s  say  that  you  want  to  folk  a  process  to  perform  some  processing  on  your 

behalf.  UNIX  requires  that  you  perform  some  housekeeping  of  that  process.  The 
minimum  housekeeping  required  is  to  notice  when  that  process  dies  and  “reap” 
it.  You  can  register  a  waitS  event  handler,^^  which  the  Notifier  will  caU  when¬ 
ever  a  child  process  changes  state  (e.g.  dies),  by  calling: 

Notify_func 

notify_set_wait3_func  (client,  wait3_func,  pid) 
static  Notify_client  client; 

Notify_func  wait3_func; 

int  pid; 


“Reaping”  Dead  Processes  Clients  using  child  process  control  which  simply  need  to  perform  the  required 

reaping  after  a  child  process  dies  can  use  the  predefined 
notifY_default_wait3  {}  as  their  waitS  event  handler.  For  example: 


^  The  name  wait3  event  originates  from  the  wait 3(2)  system  call. 
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Results  from  a  Process 


- - -  ^  ^ 

tinclude  <sunwindow/notify .h> 

static  int  my_client_object; 

static  Notify_client  *me  =  &my^client_object ; 

int  pid; 

if  (  (pid  =  my_fork  (>  )  ) 

(void)  notify_set_wait3_func (me,  notify_default_wait3, 

pid)  ; 

/*  Start  dispatching  events  */ 

(void)  notify_start  () ; 

_ _ _ _ _ _ _ 


This  is  sufficient  to  have  your  child  process  reaped  on  its  death.  The  Notifier 
automatically  removes  a  dead  process’s  wait3  event  handler  from  its  internal  data 
structures. 

NOTE  The  use  of  me  as  a  client  handle  is  arbitrary,  but  illustrates  one  method  of  gen¬ 

erating  a  unique  client  handle. 

A  more  interesting  application  might  actually  receive  some  results  from  the  pro¬ 
cess  it  forked.  In  this  case,  the  application  would  supply  its  own  wait3  event 
handler^**.  For  example: 

- - - - 

♦include  <sunwindow/notify.h> 

♦include  <sy s/wait. h> 

♦include  <sys/time.h> 

♦include  <sys/resource.h> 

static  Notify_value  my_wait3_handler ( ) ; 

/*  Register  a  wait3  event  handler  */ 

(void)  notify_set_wait3_func (me,  my_wait3_handler,  pid) ; 

/*  Start  dispatching  events  */ 

(void)  notify_start 0 ; 

static  Notify_value 

my_wait3_handler (me,  pid,  status,  rusage) 

Notify_client  me; 
int  pid; 

union  wait  * statu s; 

struct  rusage  * rusage; 

if  (WIFEXITED(*status) )  { 

/*  Child  process  exited  with  return  code  */ 
my_return_code_handler (me,  status->w_retcode) ; 

/*  Tell  the  notifier  that  you  handled  this  event  */ 
return  (NOTIFY_DONE) ; 

} 

/*  Tell  the  notifier  that  you  ignored  this  event  */ 
return  (NOTIFY_IGNORED)  ; 


See  the  wait(2)  manual  page  for  details  of  union  wait  and  struct  rusage. 
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Input-Pending  Events  (pipes) 


A  program  may  need  to  know  when  there  is  input  pending  on  a  file  descriptor — 
for  instance,  on  one  end  of  a  pipe.  Let’s  extend  our  previous  example  a  bit  to 
include  reading  data  from  a  pipe  connected  to  a  process  that  we  have  forked. 
You  can  register  an  input-pending  event  handler  which  the  Notifier  will  call 
whenever  whenever  there  is  input  pending  on  a  file  descriptor^^  by  calling: 


Notify_func 

not  if  y_set_input_func  (client,  input_func,  fd.) 
Notify__client  client; 

Notify_func  input_func; 
int  fd; 


The  calling  sequence  for  the  input_f  unc  ( )  you  supply  is  as  follows: 

Notify_value 
input_f unc (client ,  fd) 

Notify_client  client; 
int  fd; 


Example:  Reading  a  Pipe 


tinclude  <sunwindow/notify .h> 

static  Notify_value  my_pipe_reader () ; 

int  fildes[2]; 

/*  Create  a  pipe  */ 
if  (pipe (fildes)  ==  -1)  { 

perror ("pipe")  ; 
exit  (1) ; 

} 

/*  Register  an  input-pending  event  handler  */ 

(void)  notify_set_input_func  (me,  my__pipe_reader,  fildes  [0]); 
...  do  fork  and  dispatching  from  wait3  event  example  ... 

...  do  fork  and.  dispatching  from  wait  3  event  auunple  ... 

static  Notify_value 
ity_pipe_reader  (me,  fd) 

Notify_client  me; 
int  fd; 

/*  Read  the  pipe  (fd)  */ 

/*  Tell  the  notifier  that  the  input  event  is  handled  */ 
return  (NOTIFY_DONE) ; 


In  the  above  example,  the  application  uses  the  Notifier  to  read  from  the  pipe 
because  it  doesn’t  want  to  block  on  input  pending  on  the  pipe.  In  the  case  of  a 
SunView  program,  the  program  wants  to  return  back  to  the  Notifier’s  central 
dispatching  loop  so  that  the  user  can  interact  with  the  window  while  waiting  for 
input  to  become  available  on  the  pipe. 


The  file  descriptor  can  be  in  blocking  or  non-blocking  mode,  or  in  asynchronous  mode;  the  Notifier 
handles  both  as  long  as  you  have  used  font  1(2)  to  set  the  modes. 
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Closing  the  Pipe  When  you  close  any  file  descriptor  that  has  been  registered  with  the  Notifier  you 

should  unregister  it.  To  do  this,  call  notif  y_set_input_f  unc  { )  with  a 

notify_func  of  NOTIF Y_FUNC_NULL.96 

Signal  Events  Signals  are  UNIX  software  interrupts.  The  Notifier  multiplexes  access  to  the 

UNIX  signal  mechanism.  A  client  may  ask  to  be  notified  that  a  UNIX  signal 
occurred  either  when  it  is  received  (asynchronously)  and/or  later  during  normal 
processing  (synchronously). 

Clients  may  define  and  register  a  signal  event  handler  to  respond  to  any  UNIX 
signal  desired.  However,  many  of  the  signals  that  you  might  catch  in  a  tradi¬ 
tional  UNIX  program  may  be  being  caught  for  you  by  the  Notifier  (see  Don’t 
catch  above). 

CAUTION  Clients  of  the  Notifier  must  not  directly  catch  any  UNIX  signals  using  sig- 

nal(3)  or  sigvec(2).  Regardless  of  whether  clients  choose  synchronous  or 
asynchronous  signal  notification,  they  must  use  the  signal  event  mechanism 
described  in  this  section.  See  Section  17.2,  Restrictions, 

You  can  register  a  signal  event  handler  which  the  Notifier  will  call  whenever  a 
signal  has  been  caught  by  calling; 

NotifY_func 

notify_set_signal_func (client,  signal_func,  signal,  when) 
Notify_client  client; 

Notify_func  signal_func; 

int  signal; 

Notify_signal_inode  when; 

when  can  be  either  NOT  IF  Y_SYNC  orNOTIFY_ASYNC.  NOTIFY_SYNC 
causes  notification  during  normal  processing,  that  is,  the  delivering  of  the  signal 
is  delayed,  so  that  your  program  doesn’t  receive  it  at  an  arbitrary  time. 
NOTIFY_ASYNC  causes  notification  immediately  as  the  signal  is  received,  — 
this  mode  mimics  the  UNIX  signal (3)  semantics. 

A  signal!)  Replacement  for  You  should  rewrite  applications  tousenotify_set_signal_f  unc  (). 
Notifier  Compatibility  However,  the  Notifier  routine  notif  Y_set_signal_f  unc  { )  does  not  fully 

emulate  the  s ignal(3)  function.  It  does  not  handle  errors  the  same  way  sig- 
nal(3)  does.  Errors  from  signal(3)  are  indicated  by  a  -1  return  value,  and 
the  value  of  errno  is  set  to  EINVAL. 


The  errors  for  not  if  y_set__signal_f  unc  ( )  are  not  communicated  back  to 
the  caller,  but  error  messages  are  printed.  For  example,  if  the  signal  number  is 
not  valid,  the  Notifier  prints 


r 

"N 

Bad  signal  number 

but  its  return  value  indicates  success;  the  signal(3)  system  call  does  not  print  a 
message,  but  returns  -1  and  sets  errno  to  EINVAL.  As  another  example,  if 


This  method  of  passing  in  a  NOT  IF  Y  FUNC  NULL  to  unregister  an  event  handler  from  the  Notifier 
works  fOT  any  type  of  event 


sun 

microsystems 


Revision  A,  of  May  9, 1988 


292  SunView  1  Programmer’s  Guide 


SIGKILL  or  SIGSTOP  are  ignored  or  a  handler  supplied,  the  Notifier  prints 

C - - \ 

Notifer  assertion  botched:  Unexpected  error:  sigvec 


but  its  return  value  indicates  success,  while  signal(3)  does  not  print  a  message, 
returns  value  of  -1,  and  sets  errno  to  EINVAL. 


The  work-around  is  to  use  the  following  replacement  function  for  the  C  library 
version  of  signal(3).  This  code  converts  signal  ( )  calls  into 
notif  Y_set_signal_func  ( )  calls.  Explicitly  loading  this  code  will  over¬ 
ride  the  loading  of  the  C  library’s  version  of  signal  ( > .  This  approach  works 
only  if  aU  the  signal  handlers  registered  by  signal  ( )  only  look  at  the  first 
argument  passed  to  them  when  a  signal  is  received.  Also,  no  Notifier  client  han¬ 
dle  may  be  a  small  integer. 


finclude  <sunwindow/notify .h> 

#include  <errno.h> 

int  (* 

signal  (sig,  func) )  () 
int  sig,  (*func)  () ; 

if  (  (sig  <  1  i I  sig  >  NSIG)  | I 

(sig  ==  SIGKILL  | |  sig  ==  SIGSTOP)  )  { 
errno  =  EINVAL; 
return (BADSIG) ; 

} 

if  (sig  ==  SIGCONT  &&  func  ==  SIG_IGN}  { 
errno  =  EINVAL; 
return (BADSIG) ; 

} 

return  (  (int  (*)()) notify_set_signal_func (sig,  func, 

sig,  NOTIFY_ASYNC) ) ; 

s _ ^ 


Example:  Writing  to  a  Pipe  Let’s  extend  our  on-going  example  by  writing  on  the  pipe.  Writing  to  a  pipe  that 

has  no  process  at  the  other  end  to  receive  the  message  causes  a  S IGP IPE  to  be 
generated  by  UNIX.  By  default,  an  uncaught  S IGP  IPE  causes  a  premature  pro¬ 
cess  tennination.  So,  we  are  going  to  catch  S  IGP  IPE  so  that  our  process 
doesn’t  get  killed  if  we  start  a  process  that  dies.^^ 


^  We  are  glossing  over  the  part  about  actually  writing  to  the  pipe.  If  we  wanted  to  write  something  to  the 
pipe  and  then  get  some  notification  about  when  the  write  had  actually  completed  (i.e.,  the  other  process  had  read 
it)  we  would  use  the  not  if  y  set  output  f  unc  ( )  call.  The  calling  sequences  for  this  routine  and  its 
event  handler  are  exactly  the  same  as  those  for  not  i  f  y_set_input_func  ( )  Q)reviously  described). 


A  sun 

microsystenfis 


Revision  A,  of  May  9,  1988 


Chapter  17  —  The  Notifier  293 


- —  , 

♦include  <sunwindow/notify .h> 

♦include  <signal.h> 

static  NotifY_value  my_sigpipe_handler () ; 

...  do  pipe  from  input-pending  example  ... 

...  do  notify_set_input_func  from  input-pending  example  ... 

...  do  fork  from  waits  evenX  example  ... 

/*  Register  a  signal  event  handler  */ 

(void)  notify_set_signal_func (me,  my_sigpipe_handler, 

SIGPIPE,  NOTIFY_ASYNC) ; 

/*  Write  a  message  on  the  pipe  */ 


/*  Start  dispatching  events  */ 

(void)  notify_start () ; 

static  Notify_value 

my_sigpipe_handler (me,  signal,  when) 

Notify_client  me; 

int  signal; 

Notify_signal_mode  when; 

/* 

*  This  is  a  no-op  function  meant  only  to  prevent  us  from 

*  being  killed  because  we  didn't  have  a  SIGPIPE  handler. 

*/ 

return  (NOTIFY_IGNORED) ; 

> _ _ _ 

This  example  wouldn’t  actually  show  my_s igpipe_handler  ( )  being  called 
unless  you  set  up  the  child  process  to  die  right  away. 

Asynchronous  Event  Handling  An  asynchronous  signal  notification  can  come  at  any  time  (unless  blocked  using 

sigblock(2)).  This  means  that  the  client  can  be  executing  code  at  any  arbi¬ 
trary  place.  Great  care  must  be  exercised  during  asynchronous  processing. 

It  is  rarely  safe  to  do  much  of  anything  in  response  to  an  asynchronous  signal. 
Unless  your  program  has  taken  steps  to  protect  its  data  from  asynchronous 
access,  the  only  safe  thing  to  do  is  to  set  a  flag  indicating  that  the  signal  has  been 
received. 

When  in  an  asynchronous  signal  event  handler,  the  signal  context  and  signal  code 
is  available  from  the  follow  routines: 

int 

nGtify_get__signal_code  () 

struct  sigcontext  * 
notify_get_signal_context  () 

The  return  values  of  these  routines  are  undefined  if  called  from  a  synchronous 
signal  event  handler. 
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O 


Notify_func 

notify_set_itimer_func (client,  itimer_func,  which,  value, 

ovalue) 

Notify_client  client; 

Notify_func  itimer_func; 

int  which; 

struct  itimerval  *value,  *ovalue; 

The  semantics  of  which,  value  and  ovalue  parallel  the  arguments  to  seti- 
timer(2)  (see  the  getitimer(2)  manual  page),  which  is  either 
ITIMER_REAL  or  ITIMER_VIRTUAL. 

Example:  Periodic  Feedback  Asanexample,  we  want  to  provide  some  form  of  blinking  feedback.  We  do  this 

by  setting  up  an  interval  timer  when  we  want  to  blink.  We  turn  the  internal  timer 
off  when  we  no  longer  need  the  blinking.^^ 


Timeout  Events  A  client  may  require  notification  of  an  expired  timer  based  on  real  time  (approxi¬ 

mate  elapsed  wall  clock  time;  ITIMER_real)  or  on  process  virtual  time  (CPU 
time  used  by  this  process;  itimer_virtual).  To  receive  this  type  of 
notification,  the  client  must  define  and  register  a  timeout  event  handler. 


Hus  code  segment  should  be  wrapped  in,  say,  a  panel  notify  procedure,  in  order  to  be  actually  run. 
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finclude  <sunwindow/notify .h> 

#include  <sys/time .h> 

static  int  blinking_required;  /*  blirrking  desired  */ 
static  int  blinking;  /*  blinking  enabled  */ 

fdefine  ITIMER_NULL  ((struct  itimerval  *)0) 
static  Notify_value  my_blinker (} ; 

if  (blinking_required  &&  ! blinking)  { 

struct  itimerval  blink_timer; 

/*  Set  up  interval  with  which  to  RELOAD  the  timer  */ 
blink_timer. it_interval . tv_usec  =0; 
blink_timer. it_interval.tv_sec  =1; 

/*  Set  up  INITIAL  value  with  which  to  SET  the  timer  */ 
blink_timer . it_value . tv_usec  =0; 
blink_timer. it_value .tv_sec  =  1; 

/*  Turn  on  interval  timer  for  client  */ 

(void)  notify_set_itimer_func (me,  my_blinker, 
ITIMER_REAL,  &blink_timer,  ITIMER_NULL) ; 
blinking  =1; 

}  else  if  ( !blinking_required  &&  blinking)  { 

/*  Turn  off  interval  timer  for  client  */ 

(void)  notify_set_itimer_func (me,  my_blinker, 
ITIMER_REAL,  ITIMER_NULL,  ITIMER_NULL) ; 
blinking  =0; 

} 

static  Notify_value 
my_blinker (me,  which) 

Notify_client  me; 
int  which; 

/*  Do  the  blink  */ 

return  (N0TIFY_D0NE) ; 


Polling  Interval  timers  can  be  used  to  set  up  a  polling  situation.  There  is  a  special 

value  argument  to  not  if  y_set_it  imer_f  unc  ( )  that  tells  the  Notifier  to 
caU  you  as  often  and  as  quickly  as  possible.  This  value  is  the  address  of  the 
following  constant; 

struct  itimerval  NOTIFY__POLLING_ITIMER;  /*  {  {  0,  1 }  /  { 0, 1 }  }  */ 

This  high  speed  polling  can  consume  all  of  your  machine’s  available  CPU  time, 
but  may  be  appropriate  for  high  speed  animation.  It  is  used  in  the  program 
spheres,  which  shows  one  way  to  convert  and  old  SunWindows  gfs  subwindow- 
based  program  to  SunView.  spheres  is  explained  in  Appendix  C,  Converting 
SunWindows  Programs  to  SunView,  and  is  listed  in  fuU  in  in  Appendix  A,  Exam¬ 
ple  Programs. 
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Checking  the  Interval  Timer  The  following  function  checks  on  the  state  of  an  interval  timer  by  returning  its 

current  state  in  the  structure  pointed  to  by  value. 

Notify_error 

notify_itimer_value (client,  which,  value) 

Notify_client  client; 

int  which; 

struct  itimerval  * value; 


Turning  the  Interval  Timer  Off  If  you  specify  an  interval  timer  with  its  it__int  erval  structure  set  to 

{ 0 ,  0 } ,  the  Notifier  flushes  any  knowledge  of  the  interval  timer  after  it  delivers 
the  timeout  notification.  Otherwise,  supplying  a  NULL  interval  timer  pointer  to 
notif  y_set_itimer_f  unc  ( )  will  turn  the  timer  off. 


17,5.  Interposition  SunView  window  objects  utilize  the  Notifier  for  much  of  their  communication 

and  cooperation.  The  Notifier  provides  a  mechanism  called  interposition,  with 
which  you  can  intercept  control  of  the  internal  communications  within  SunView. 
Interposition  is  a  powerftil  way  to  both  monitor  and  modify  window  behavior  in 
ways  that  extend  the  functionality  of  a  window  object. 

Interposition  allows  a  client  to  intercept  an  event  before  it  reaches  the  base  event 
handler.  The  base  event  handler  is  the  one  set  originally  by  a  client.  The  client 
can  call  the  base  event  handler  before  or  after  its  own  handling  of  the  event,  or 
not  at  aU.  Qients  may  use  interposition  to  monitor  and  filter  events  coming  in  to 
an  event  handler  and/or  to  modify  a  series  of  actions  based  on  the  results  of  some 
calculation. 

How  Interposition  Works  A  client  requests  that  the  Notifier  install  an  interposer  function,  supplied  by  the 

client,  for  a  specified  client  and  type  of  event.  \^en  an  event  arrives,  the 
Notifier  calls  the  function  at  the  top  of  the  wait  list  for  that  client  and  that  type  of 
event  An  interposed  routine  may  (indirectly)  call  the  next  function  in  the  inter¬ 
position  sequence  and  receive  its  results. 

Figure  17-2  illustrates  the  flow  of  control  with  interposition.  Note  that  the  inter¬ 
poser  could  have  stopped  the  flow  of  control  to  the  base  event  handler. 
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Figure  17-2  Flaw  of  Control  in  Interposition 


Monitoring  a  Frame’s  State  You  can  notice  when  a  frame  opens  or  closes  by  interposing  in  front  of  the 

frame’s  client  event  handler.  The  client  event  handler  is  a  SunView  specific 
event  handler  which  is  built  on  top  of  the  Notifier’ s  general  client  event  mechan¬ 
ism.^^  To  install  an  interposer  call  the  following  routine: 

Notify__error 

notify_interpose_event_func (client,  event_func,  type) 
Notify_client  client; 

Notify_func  event__func; 

Notify_event_type  type; 

client  must  be  the  handle  of  the  Notifier  client  in  front  of  which  you  are  inter¬ 
posing.  In  SunView,  this  is  the  handle  returned  from  winciow_create  ( ) 
type  is  always  N0TIFY_SAFE  for  SunView  clients. 

Example:  Interposing  on  Let’s  say  that  the  application  is  displaying  some  animation,  and  wants  to  do  the 

Open/Close  necessary  computation  only  when  the  frame  is  open.  It  can  use  interposition  to 

notice  when  the  frame  opens  or  closes. 

The  program  spheres  (which  shows  one  way  to  convert  an  old  SunWindows  gfx 
subwindow-based  program  to  SunView)  uses  this  technique  to  stop  shading  an 
image  when  its  frame  is  closed.  It  is  explained  in  Appendix  C,  Converting 
SunWindows  Programs  to  SunView,  and  is  listed  in  fijU  in  in  Appendix  A,  Exam¬ 
ple  Programs. 

Another  example  appears  on  the  following  page.  Note  the  the  call  to 
notif  y_next_event_func  ( ) ,  which  transfers  control  to  the  frame’s  client 
event  handler  through  the  Notifier.  not  if  y_next_event_f  unc  ( )  takes  the 
same  arguments  as  the  interposer. 


^  The  stream  of  events  sent  to  a  client  event  handler  is  described  in  in  Chiller  6,  Handling  Input. 
It  could  also  be  the  handle  returned  from  the  call  to  scrollbar  create  ( ) . 
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#include  <suntool/sunview.h> 


static  Notify  value  my  frame  interposer () ; 


Frame  frame; 

/*  Create  the  frame  */ 

frame  =  window  create  (0,  FRAME, 


/*  Interpose  in  front  of  the  frame's  event  handler  */ 
(void)  notify_interpose_event_func (frame, 

my_f rame_interposer,  NOTIFY_SAFE) ; 
/*  Show  frame  and  start  dispatching  events  */ 
window_main_loop (frame) ; 

static  Notify_value 

my_frame_interposer (frame,  event,  arg,  type) 

Frame  frame; 

Event  * event; 

Notify_arg  arg; 

Notify_event_type  type; 

int  closed_initial,  closed_current ; 

Notify_value  value; 

{ 

/*  Determine  initial  state  of  frame  */ 

closed_initial  =  (int)  window_get (frame,  FRAME_CLOSED) ; 

/*  Let  frame  operate  on  the  event  */ 

value  =  notify_next_event_func (frame,  event,  arg,  type) ; 
/*  Determine  current  state  of  frame  */ 

closed_current  =  (int)  window_get (frame,  FRAME_CLOSED) ; 

/*  Change  animation  if  states  differ  */ 
if  (closed_initial  !=  closed_current )  { 

if  (closed_current )  { 

/*  Turn  off  animation  because  closed  */ 

(void)  notify_set_itimer_func  (me,  my__animation, 
ITIMER_REAL,  ITIMER_NULL,  ITIMER_NULL) ; 

}  else  { 

/*  Turn  on  animation  because  opened  */ 

(void)  notify_set_itimer_func (me,  my_animation , 
ITIMER_REAL,  &NOTIFY_POLLING_ITIMER, 

ITIMER  NULL) ; 


return  (value) ; 
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Discarding  the  Default  Action  In  the  example  on  the  preceding  page,  you  wanted  the  base  event  handler  to  han¬ 
dle  the  event  (so  that  the  frame  gets  closed/opened).  If  the  interposed  function 
replaces  the  base  event  handler,  and  you  don’t  want  the  base  event  handler  to  be 
called  at  all,  your  interposed  procedure  should  not  call 

not  if  Y_next_event  { ) .  For  example,  your  interposed  function  might  han¬ 
dle  scroll  events  itself,  so  you  would  not  want  the  base  event  handler  to  perform 
an  additional  scroU. 

Interposing  on  Resize  Events  Another  common  use  of  interposition  is  to  give  your  application  more  control 

over  the  layout  of  its  subwindows.  The  code  is  very  similar.  You  call 
notify_interpose_event_func  ( )  to  interpose  your  event  handler.  In 
the  event  handler,  the  following  fragment  could  be  used: 

<  ^  > 
value  =  notify_next_event_func (frame,  event,  arg,  type); 
if  (event_act ion (event)  ==  WIN_RESIZE) 
resize (frame) ; 
return (value) ; 

_ i 


Let  the  default  event  handler  handle  the  event,  then  check  if  the  event  is  a  resize 
event.  If  so,  call  your  own  resize  { )  procedure  to  lay  out  the  subwindows. 


NOTE  A  WIN_RES  I ZE  event  is  not  generated  until  the  frame  is  resized.  If  you  want 
your  resize  procedure  to  be  called  when  the  window  first  appears  you  must  do  so 
yourself.  This  is  different  from  a  canvas  with  the  CANVAS_RESIZE  attribute 
'  set,  whose  resize  procedure  is  called  the  first  time  the  canvas  is  displayed. 

If  the  user  manually  adjusts  subwindow  sizes  using  I  Control  1-middle  mouse  but¬ 
ton,  no  WIN_RESIZE  event  is  generated.  You  can  disallow  subwindow  resizing 
by  setting  the  frame_subwindows_ad  justable  attribute  to  false. 

Example:  resize_demo  The  program  resize_demo  shows  how  to  achieve  more  complex  window  layouts 

than  possible  using  window  layout  attributes.  It  is  listed  in  Appendix  A,  Exam¬ 
ple  Programs. 

Modifying  a  Frame’s  Suppose  an  application  must  detect  when  the  user  selects  the  ‘Quit’  menu  item  in 

Destruction  the  frame  menu,  in  order  to  perform  some  application-specific  confirmation.  We 

have  to  interpose  in  front  of  the  frame’s  client  destroy  event  handler  using  the 
following  routine. 

Notify_error 

notify_interpose_destroy_func (client,  destroy_func) 
Notify_client  client; 

Notify_func  destroy_func; 

First,  however,  you  need  to  understand  client  destroy  events. 
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Destroy  Events 


Checking 


Destruction 


A  Typical  Destroy  Handler 


The  Notifier  can  tell  each  client  to  destroy  itself.  It  is  possible  for  a  destroy  event 
handler  to  receive  two  calls  concerning  client  destruction:  one  call  may  be  a 
status  inquiry  and  the  other  a  demand  for  termination.  Destroy  event  handlers 
use  a  status  code  to  determine  whether  the  caller  demands  actual  termination 
(DESTROY_CLEANUP  or  DESTROY_PROCESS_DEATH),  or  simply  requires  an 
indication  if  it  is  feasible  for  the  client  to  terminate  at  present 
DESTROY_CHECKING). 

If  the  status  argument  indicates  an  inquiry  and  the  client  cannot  terminate  at 
present,  the  destroy  event  handler  should  call  notif  Y_veto_destroY  { ) , 
indicating  that  termination  would  not  be  advisable  at  this  time,  and  return  nor¬ 
mally.  If  the  St  at  us  argument  indicates  an  inquiry  and  the  client  can  terminate 
at  present,  then  the  destroy  handler  should  do  nothing;  a  subsequent  call  will  tell 
the  client  to  actually  destroy  itself. 

This  veto  option  is  used,  for  example,  to  give  a  text  subwindow  the  chance  to  ask 
the  user  to  confirm  the  saving  of  any  editing  changes  when  quitting  a  tool. 

If  the  status  argument  is  not  DESTROY_CHECKING  then  the  client  is  being 
told  to  destroy  itself.  If  status  is  DESTROY_PROCESS_DEATH  then  the 
client  can  count  on  the  entire  process  dying  and  so  should  do  whatever  it  needs  to 
do  to  cleanup  its  outside  entanglements,  e.g.,  update  a  file  used  by  other 
processes.  Since  the  entire  process  is  dying,  one  might  choose  to  not  release  aU 
the  resources  used  within  the  process,  e.g.,  dynamically  allocated  memory. 
However,  if  status  is  destroy_CLEANUP  then  the  client  is  being  asked  to 
destroy  itself  and  be  very  tidy  about  cleaning  up  aU  the  process  internal  resources 
that  it  is  using,  as  well  as  its  outside  entanglements. 


A  typical  destroy  handler  looks  like  the  following: 


Notify_value 

coiTmion_destroy_func (client,  status) 

Notify_client  client; 

Destroy_status  status; 
if  (status  ==  DESTROY_CHECKING)  { 

if  (/*  Don't  want  to  go  away  now  */) 
notify_veto_destroy (client) ; 

}  else  { 

/*  Always  release  external  conmiitments  */ 
if  (status  ==  DESTROY_CLEANUP) 

/*  Conditionally  release  internal  resources  */ 

} 

return  (NOTIFY  DONE) ; 
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Example:  Interposing  a  Qient 
Destroy  Handler 


Now  we  can  present  the  example  of  interposing  in  front  of  the  frame’s  client  des¬ 
troy  event  handler.  In  addition  to  doing  our  own  confirmation,  we  prevent  dou¬ 
ble  confirmation  by  suppressing  the  frame’s  default  confirmation. 

Note  that  after  having  the  destroy  OK’d  by  the  user,  we  call 

notif  y_next_destroy_f  unc  ( }  before  returning.  This  allows  other 

subwindows  to  request  confirmation. 

The  code  appears  on  the  following  page. 
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♦include  <suntool/sunview.h> 


static  Notify_value  my_frame_destroyer  () ; 


*  Interpose  in  front  of  the  frame' s  destroy  event  handler 
*/ 

(void)  notify__interpose_destroy_func  (frame, 

niy_f rame_destroyer) ; 

/*  Show  frame  and  start  dispatching  events  */ 
window  main  loop (frame) ; 


static  Notify_value 
my_frame_destroyer (frame,  status) 

Frame  frame; 

Destroy_status  status; 

if  (status  ==  DESTROY_CHECKING)  { 

if  {my  internal  state  requires  cor^rmation)  { 

/* 

*  Request  confirmation  from  the  user 

*  (see  window_loop()  in  the  index)  . 

*/ 


if  {destroy  OK d  by  user)  { 

/*  Tell  frame  not  to  do  confirmation  */ 
window_set  (frame,  FR2daE_NO_CONFIRM,  TRUE,  0)  ; 
}  else  { 

/* 

*  Tell  the  Notifier  that  the  destroy  has 

*  been  vetoed. 

*/ 

(void)  notify_veto_destroy (frame) ; 

/* 

*  Return  now  so  that  the  destroy  event 

*  never  reaches  the  frame's  destroy  handler. 
*/ 

return  (NOTIFY_DONE) ; 

} 

}  else  { 

/*  Let  frame  do  normal  confirmation  */ 
window  set (frame,  FRAME  NO  CONFIRM,  FALSE,  0); 


/*  Let  frame  get  destroy  event  */ 

return  (notify_next_destroy_func (frame,  status)); 
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Most  programs  that  are  ported  to  SunView  are  not  notification-based.  They  are 
traditional  programs  that  maintain  strict  control  over  the  inner  control  loop. 

Much  of  the  state  of  such  programs  is  preserved  on  the  stack  in  the  form  of  local 
variables.  The  Notifier  supports  this  form  of  programming  so  that  you  can  use 
SimView  packages  without  inverting  the  control  structure  of  your  program  to  be 
notification-based. 

Explicit  Dispatching  The  simplest  way  to  convert  a  program  to  coexist  with  the  Notifier  is  called 

explicit  dispatching.  This  approach  replaces  the  call  to 

window_main_loop  ( ) ,  which  usually  doesn’t  return  xmtil  the  application  ter¬ 
minates,  with  the  following  bit  of  code: 


notif  y_dispat  ch  { )  goes  once  around  the  Notifier’s  internal  loop, 
dispatches  any  pending  events,  and  returns.  You  should  try  to  have 
notif  y_dispatch  ( )  called  at  least  once  every  1/4  second  so  that  good 
interactive  response  with  SunView  windows  can  be  maintained. 

The  program  bounce  (which  shows  one  way  to  convert  an  old  SunWindows  gfx 
subwindow-based  program  to  SunView)  uses  explicit  dispatching.  It  is 
explained  in  Appendix  C,  Converting  SunWindows  Programs  to  SunView,  and  is 
given  in  fuU  in  in  Appendix  A,  Example  Programs. 

Implicit  Dispatching  Explicit  dispatching  is  good  when  you  are  performing  some  computationally 

intensive  processing  and  you  want  to  occasionally  give  the  user  a  chance  to 
interact  with  your  program.  There  is  another  method  of  interacting  with  the 
Notifier  that  is  useful  when  you  simply  want  the  Notifier  to  take  care  of  its  clients 
and  block  until  there  is  something  of  interest  to  you.  This  is  called  implicit 
dispatching. 

This  time,  we  replace  the  call  to  window_main_loop  ( )  with  the  following 
bit  of  code: 


17,6.  Porting  Programs  to 
SunView 
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- —  > 

#include  <suntool/sunview.h> 

static  int  my_done; 

window_set (frame,  WIN_SHOW,  TRUE,  0); 

/*  Enable  implicit  dispatching  */ 

(void)  notify_do_dispatch 0 ; 
while  (!iny_done)  { 
char  c; 

/*  read  allows  implicit  dispatching  by  Notifier  */ 
if  ( (n  =  read(0/*stdin*/,  &c,  1))  <  0) 
perror ("my_program") ; 

} 

_ — — — - / 


not  if  y_do_dispat  ch  ( )  allows  the  Notifier  to  dispatch  events  from  within 
the  calls  to  read(2)  or  select(2).  The  Notifier’s  versions  of  read(2)  and 
select  (2)  won’t  return  until  the  normal  versions  would.  They  can  block 
exactly  like  the  normal  versions. 

not  if  y_no_dispat  ch  ( )  (it  takes  no  arguments)  prevents  the  Notifier  from 
dispatching  events  from  within  the  call  to  read(2)  or  select(2). 

Getting  Out  When  you  use  either  of  these  dispatching  approaches,  you  will  need  to  find  out 

when  the  frame  is  ‘Quit’  by  the  user,  in  order  to  know  when  to  terminate  your 
program.  To  do  so,  interpose  in  front  of  the  frame’s  destroy  event  handler,  as  in 
the  previous  section,  so  that  you  can  notice  when  the  frame  goes  away.  At  this 
point  you  can  caU  notif  y_stop  ( )  to  break  the  read(2)  or  select(2)  out 
of  a  blocking  state. 
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17.7.  Error  Handling 
Error  Codes 


Handling  Errors 


- -  , 

finclude  <suntool/sunview.h> 

static  int  my_done; 

static  Notify_value  iny_notice_destroy  ( ) ; 

/* 

*  Interpose  in  front  of  the  frame' s  destroy  event  handler 
*/ 

(void)  notify_interpose_destroy_func (frame, 

my_notice_destroy) ; 

static  Notify_value 
n^_notice_destroy (frame,  status) 

Frame  frame; 

Destroy_status  status; 

if  (status  !=  DESTROy_CHECKING)  { 

/*  Set  my  flag  so  that  I  terminate  my  loop  soon  */ 
my_done  =  1; 

/*  Stop  the  notifier  if  blocked  on  read  or  select  */ 
(void)  notify_stop ( ) ; 

} 

/*  Let  frame  get  destroy  event  */ 

return  (notify_next_destroy_func (frame,  status)); 
s _ 


Every  call  to  a  notifier  routine  returns  a  value  that  indicates  success  or  failure. 
Routines  that  return  an  enumerated  type  called  Notif  y_error  deliver 
N0TIFY_0K  (zero)  to  indicate  a  successful  operation,  while  any  other  value 
indicates  failure.  Routines  that  return  function  pointers  deliver  a  non-nuU  value 
to  indicate  success,  while  a  value  of  notify_func_NULL  indicates  an  error 
condition. 

When  an  error  occurs,  the  global  variable  not  if  y_errno  describes  the  failure, 
The  Notifier  sets  not  if  y_errno  much  like  UNIX  system  calls  set  the  global 
err  no;  that  is,  the  Notifier  only  sets  not  if  y_errno  when  it  detects  an  error 
and  does  not  reset  it  to  NOT  IF  Y_OK  on  a  successful  operation.  A  table  in  the 
SunView  1  System  Programmer’s  Guide  lists  each  possible  value  of 
notif  y_errno  and  its  meaning. 

Most  of  the  errors  returned  from  the  Notifier  indicate  a  programmer  error,  e.g., 
the  arguments  are  not  valid.  Often  the  best  approach  for  the  client  is  to  print  a 
message  if  the  return  value  is  non-zero  and  exit.  The  procedure 
notif  y_perror  ( )  takes  a  string  which  is  printed  to  stderr,  followed  by  a 
colon,  followed  by  a  terse  description  of  notif  y_errno.  This  is  done  in  a 
manner  analogous  to  the  UNIX  perror(3)  call. 


microsystems 


Revision  A,  of  May  9,  1988 


306  SimView  1  Programmer’s  Guide 


Debugging 


Here  are  some  debugging  hints  that  may  prove  useful  when  programming: 


NOT  lFY_ERROR_ABORT  Setting  the  environment  variable  notify_error_abort  to  yes  will  cause 

the  Notifier  to  abort  with  a  core  dump  when  the  Notifier  detects  an  error.  This  is 
useful  if  there  is  some  race  condition  tiiat  produces  notifier  error  messages  that 
you  are  having  a  hard  time  tracking  down. 


Stop  in  not  if  y_per  r  or  ( )  If  you  are  getting  notifier  error  messages,  but  don’t  know  from  where,  try  putting 

or  fprint  f  (3S)  a  break  point  on  the  entry  to  either  not  if  y_perror  ( )  or  fprintf  (3S). 

Trace  the  stack  to  see  what  provoked  the  message. 


n  o t  i  f  y_dump  The  following  call  can  be  made  from  the  debugger  or  your  program  to  dump  a 

printout  of  the  state  of  the  Notifier: 

void 

not if y_dump (client,  type,  file) 

Notify_client  client; 
int  type; 

FILE  *file; 

The  state  of  client  is  dumped  to  file  based  on  the  value  of  type.  If 
client  is  0  then  aU  clients  are  dumped.  If  type  is  1  then  aU  the  registered 
event  handlers  are  dumped.  If  type  is  2  then  all  the  events  pending  for  delivery 
are  dumped.  If  type  is  3  then  both  the  registered  event  handlers  and  the  events 
pending  for  delivery  are  dumped.  If  file  is  1  then  stdout  is  assumed.  If  file 
is  2  then  stderr  is  assumed.  To  be  able  to  call  notif  y_dump  { )  you  need  to 
reference  it  from  some  place  in  your  program  so  that  it  gets  loaded  into  your 
binary. 
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Attribute  Utilities 


This  chapter  describes  macros  and  functions  that  are  provided  as  utilities  to  be 
used  with  attributes. 


18.1.  Character  Unit  By  default  in  SunView,  coordinate  specification  attributes  interpret  their  values 

Macros  in  pixel  units.  For  applications  that  don’t  make  heavy  use  of  images,  it  is  usually 

more  convenient  to  specify  positions  in  character  units  —  columns  and  rows 
rather  than  xs  and  ys.  To  this  end  two  macros  attr_row  ( )  and  attr_COL  ( } 
are  provided,  which  interpret  their  arguments  as  rows  or  columns,  respectively, 
and  convert  the  value  to  the  corresponding  number  of  pixels,  based  on  the 
subwindow’s  font,  as  specified  by  WIN_F0NT.  attr_ROW  ( )  and 
ATTR_COL  { )  take  as  arguments  any  expression  yielding  an  integer.  The  use  of 
these  macros  as  an  operand  in  an  expression  is  restricted  to  adding  a  pixel  offset 
(e.g.,  ATTR_ROW(5)  +  2).  Examples  of  legal  and  illegal  usage  are  given  in  the 
table  below. 


Table  18-1 


Example  uses  of  the  ATTR_ROW  ( )  and  ATTR_COL  ( )  macros 


PANEL_ITEM_X 
PANEL_ITEM_Y 
PANEL_ITEM_X 
PANEL_ITEM_X 
PANEL_ITEM_X 
PANEL_ITEM_X 
PANEL_ITEM_X 
PANEL_ITEM_Y 
PANEL_ITEM_Y 
PANEL_ITEM_Y 
PANEL_ITEM_Y 
PANEL_ITEM_Y 
PANEL_ITEM_X 
PANEL  ITEM  X 


Attribute/Value _ 

,  5 
,  10 

,  ATTR_COL(5) 

,  ATTR_COL(-5) 

,  ATTR_COL(5+2) 

,  ATTR_COL(5)+2 
,  ATTR_COL(5) -1 
,  ATTR_ROW(10) 

,  ATTR_R0W(-10) 

,  ATTR_ROW(10+2) 

,  ATTR_ROW(10)+2 
,  ATTR_ROW(10) -1 
,  ATTR_COL (10) +ATTR_COL ( 2 ) 
,  2*ATTR  COL (10) 


Interpretation 
5  pixels  from  left 
10  pixels  from  top 
cx)lumn  5 
column  -5 
column  7 

2  pixels  to  right  of  col  5 

1  pixel  to  left  of  col  5 
row  10 

row  -10 
row  12 

2  pixels  down  from  row  10 
1  pixel  up  from  row  10 
illegal 

illegal 


NOTE  ATTR_ROW()  ant/ ATTR_COL  ( )  treat  their  arguments  as  character  positions 
rather  than  lengths.  In  other  words,  when  you  use  ATTR_ROW(5),  the  pixel 
value  that  is  computed  includes  the  top  margin.  Similarly,  the  pixel  value  com¬ 
puted  using  ATTR_C0L(5)  includes  the  left  margin. 
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These  macros  can  be  used  with  the  panel  attributes  or  the  window  attributes  such 
as  WIN  X,  WIN  HEIGHT,  etc. 


Both  the  attributes  and  the  ATTR_ROW  { )  and  attr_COL  ( }  macros  are  zero- 
based  —  that  is,  the  first  row  is  row  zero. 


If  you  want  to  use  lengths  rather  than  positions,  you  can  use  the  alternate  macros 
ATTR_ROWS  ( )  and  ATTR_COLS  ( ) .  Examples  of  the  differences  between  the 
character  position  and  length  macros  are  given  in  the  table  below. 


Table  18-2  Example  uses  of  the  ATTR_ROWS{)  and  ATTR_COLS()  macros 


Attribute/Value 

Interpretation 

WI N_WI DTH ,  ATTR_COL (80) 

80  characters  wide  +  left  margin 

WIN_WIDTH,  ATTR_COLS(80) 

exactly  80  characters  wide 

WI N_HE I GHT ,  ATTR_ROW (24) 

24Jines  high  +  top  margin 

WI N_HE I GHT ,  ATTR_ROWS (24) 

exactly  24  lines  high 

PANEL_ITEM_X,  ATTR_COL (5) 

col  5  (left  margin  +  5  character  widths) 

PANEL_ITEM_X,  ATTR_COLS (5) 

5  character  widths  from  the  left  edge 

PANEL_ITEM_Y ,  ATTR_ROW ( 5 ) 

row  5  (top  margin  +  5  row  heights) 

PANEL_ITEM_y,  ATTR_ROWS (5) 

5  row  heights  from  the  top  edge 

18.2.  Creating  Reusable 
Attribute  Lists 


You  may  want  to  create  an  attribute  list  that  can  be  passed  to  different  routines. 
You  can  do  this  either  by  creating  the  list  explicitly,  or  by  using  the  routine 
attr_create_list  {) . 


To  create  an  attribute  list  explicitly,  define  a  static  array  of  char  *,  which  is 
initialized  (or  later  fiUed  in  with)  the  desired  attribute/value  pairs.  Note  that 
non-string  values  must  be  coerced  to  type  char 


static  char  *attributes []  =  { 

(char*) PANEL_LABEL_STRING, 

"Name:  ", 

(Char*) PANEL_VALUE, 

"Goofy  ”, 

(char*) PANEL  NOTIFY  PROG, 

0  } 

(char  *)  name_item_jproc. 

Vs _ 

_  j 

To  make  an  attribute  list  dynamically,  use; 

Attr_avlist 

attr_create_list (attributes) 

<attribute-list>  attributes; 

attr_create_list  ( )  allocates  storage  for  the  list  it  returns.  It  is  up  to  you 
to  free  this  storage  when  no  longer  needed,  as  in; 
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- - - ^  > 

Attr_avlist  list; 

list  =  attr_create _ list (PANEL_LABEL_BOLD,  TRUE,  0); 

free (list) ; 


The  free  ( )  procedure  is  the  standard  UNIX  f  ree(3)  routine. 

Default  Attributes  The  code  below  shows  how  to  use  att r_cr  eat e_li  st  ( )  in  conjunction 

with  the  attribute  attr_list  to  support  default  attributes  in  a  panel. 


int 

text_proc ( ) ,  name_proc ( ) ; 

Panel  item 

name  item,  address_item; 

Pixfont 

*big  font,  *small_font; 

Attr_avlist 

defaults; 

defaults  = 

attr  create  list ( 

PANEL  SHOW  ITEM, 

FALSE, 

PANEL  LABEL_FONT, 

big  font. 

PANEL  VALUE_FONT, 

small_font. 

PANEL  NOTIFY_PROC, 

text_proc. 

0); 

name  item  = 

panel  create_it em (PANEL_TEXT , 

ATTR_LIST, 

defaults. 

P ANEL_NOT I FY_PROC , 

name_proc. 

0); 

address  item  =  panel  create  item (PANEL_TEXT, 

ATTR  LIST, 

defaults. 

PANEL  SHOW  ITEM, 

TRUE, 

PANEL_VALUE_FONT , 

big_font. 

0); 

> 

The  special  attribute  ATTR_LIST  takes  as  its  value  an  attribute  list,  hi  the 
above  example,  first  an  attribute  list  called  defaults  is  created.  Then,  by 
mentioning  default  s  first  in  the  attribute  lists  for  subsequent  item  creation 
calls,  each  item  takes  on  those  default  attributes.  Subsequent  references  to  an 
attribute  override  the  setting  in  defaults  since  the  last  value  mentioned  for  an 
attribute  is  the  one  which  takes  effect. 

18.3.  Maximum  Attribute  The  maximum  length  of  attribute-value  lists  supported  by  the  SunView  packages 
List  Size  (see  ATTR_STANDARD__S  I  ZE  in  <sunwindow/att  r .  h>)  is  250.  If  the 

number  of  attributes  in  a  list  you  pass  to  SunView  exceeds  this  size,  the  attribute 
package  prints 

- —  —  . 

Number  of  attributes  {mm)  in  the  attr  list  exceeds 
the  maximum  number  (wnn)  specified.  Exit  I 

on  standard  output  and  exits  with  exit  status  1. 
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SunView  Interface  Summary 


This  chapter  contains  tables  summarizing  the  data  types,  functions  and  attributes 
which  comprise  the  SunView  programmatic  interface. 

The  tables  correspond  to  the  chapters  in  this  book,  but  are  in  alphabetical  order: 
Alerts,  Canvases,  Cursors,  Data  Types,  Icons,  Input  (including  events  and  input- 
related  window  atttributes).  Menus,  the  Notifier,  Panels,  Pixwins,  Scrollbars, 
Text  Subwindows,  TTY  Subwindows  and  Windows  (including  frames  and  frame 
command  line  arguments). 

Note  that  the  order  of  the  chapters  is  different  than  the  order  of  the  tables.  The 
chapter  on  windows  (including  frames)  comes  first,  followed  by  canvases,  input, 
pixwins,  text  subwindows,  panels,  alerts,  tty  subwindows,  menus,  cursors,  icons, 
scroUbars,  the  Selection  Service,  and  the  Notifier. 

Within  each  topic,  the  attribute  tables  come  first,  then  the  functions  and  macros, 
then  miscellaneous  tables. 

To  help  distinguish  where  one  table  ends  and  another  begins,  the  start  of  each 
table  is  marked  with  a  horizontal  grey  bar. 


101  This  chapter  does  not  include  a  table  for  the  Selection  Service  functions;  see  the  SunView  System 
Programmer’s  Guide  for  a  complete  discussion  of  the  Selection  Service  interface. 
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Table  19-1 

Alert  Attributes 

1 

. ' . 

Attribute 

Type 

Description 

.  ALERT_BDTTON 

char  *,  int 

A  string  to  be  displayed  in  a  button  and  a  value  to  associate  with  it.  The 
value  specified  with  the  string  will  be  returned  when  the  button  is 
selected.  The  value  may  be  any  integer,  but  should  not  be  a  value 
predefined  by  the  alerts  package;  that  is,  not  ALERT_YES,  ALERT  NO, 
ALERT_F AILED,  or  ALERT_DEFAULT_TRIGGERED). 

See  the  values  given  in  the  Alert  Functions  table. 

ALERT_BUTTON_FONT 

Pixfont  * 

Font  used  for  buttons.  Default  is  the  font  specified  for  menus,  which  is 
Menu/Font  in  defaultsedit  or  screen .  b .  1 4  if  no  default  is  specified. 

ALERT_BUTTON_NO 

char  * 

A  string  that  is  associated  with  the  accelerated 

NO  (cancel,  don’t  do  it)  button  which  is  triggered  via  a 
keyboard  accelerator.  The  value  returned  if  this  button  is  selected 
(or  the  accelerator  is  triggered)  will  be  ALERT_NO.  Only  one  instance 
of  this  attribute  is  allowed. 

ALERT_BUTTON_YES 

char  * 

A  string  to  associate  with  the  accelerated 

YES  (ie.  confirm,  continue,  do  it)  button  which  is  also  triggered  via  a 
keyboard  accelerator.  The  value  returned  when  this  button  is  selected 
(or  the  accelerator  is  triggered)  will  be  ALERT  YES.  Only  one  instance 
of  this  attribute  is  allowed. 

ALERT_MESSAGE_FONT 

Pixfont  * 

Font  used  for  message  strings. 

The  default  is  the  same  as  Client  Frame  (if  specified)  otherwise  it  is  the 
same  as  SunViewlFont. 

ALERT_MESSAGE_STRINGS 

list  char* 

Strings  to  be  displayed  in  the  message 

area  of  the  alert  panel.  The  default  is  to  be  determined. 

ALERT_MESSAGE_STRINGS_ARRAY_ 

PTR  array  char* 

Same  as  ALERT_MESSAGE_STRINGS 

except  the  client  need  not  know  the  actual  strings  being  passed,  just 
that  the  value  is  pointer  to  first  of  null  terminated  array  of  strings. 

The  alerts  package  will  cast  the  value  into  a  type  char  * *. 

ALERT_NO_BEEP ING 

int 

Allows  the  client  to  specify  that  no  beeping  should 

take  place  reguardless  of  defaults  database  setting.  The  default  for  this 

option  is  FALSE;  that  is,  beep  however  many  times  database  specifies. 
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Table  19-1 

Alert  Attributes —  Continued 

Attribute 

Type 

Description 

ALERT_ 

_OPTIONAL 

boolean 

Specifies  whether  an  optional  alert  will  be  enabled 
or  disabled.  You  make  an  alert  a 
courtesy  alert  by  specifing  the  ALERT_OPTIONAL 
attribute  in  the  attribute  list  passed  to 
alert_prompt  (} . 

ALERT_ 

_POSITION 

int 

Specifies  the  position  of  the  alert. 

Default  is  ALERT_CLIENT_CENTERED  unless  client_frame  =  NULL 
NULL  causes  the  alert  to  default  to  ALERT_SCREEN_CENTERED 
regardless  of  this  setting. 

Possible  values  that  may  be  passed  are:  ALERT_SCREEN_CENTERED, 
ALERT_CLIENT_CENTERED,  and  ALERT_CLIENT_OFFSET. 

Use  WIN_X  and  'WIN_Y  for  the  offset  attributes.  This  position  describes 
where  the  “center”  of  an  alert  should  be. 

ALERT_ 

TRIGGER 

int 

This  special  attribute  allows  the  client  to 

specify  a  SunView  event  which  should  cause  the  alert  to  return.  The 
default  is  not  to  return  unless  an  actual  button  has  been  selected 
or  the  other  YES/NO  accelerators  are  seen.  When  this  event  is  triggered, 
the  value  returned  will  be  ALERT_TRIGGERED. 
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Table  19-2  Alert  Functions 

Definition 

Description 

int 

alert_prompt (client_frame,  event,  attributes) 
Frame  client  frame; 

Event  * event; 

<attribute-list>  attributes; 

Displays  alert  and  doesn’t  return  until  the  user  pushes  a 
button,  or  its  trigger  or  the  default  has  been  seen.  A  value 
of  ALERT  FAILED  is  returned  if  alert_prompt  ( ) 
failed  for  any  reason,  otherwise  equivalent  to  ordinal  value 
of  button  which  caused  return  (ie.  button  actually  selected, 
or  default  button  if  default  action  triggered  return).  The 
cliOTt_frame  may  be  NULL  (see  ALERT_POSITION  for 
consequences).  The  event  will  be  completely  fiUed  in  at 
the  time  the  alert_prompt  ()  returns. 

The  possible  status  values  that  may  be  returned  from  this 
function  are:  the  (int)  value  passed  with  every 
ALERT_BUTTON  attribute;  ALERT  YES,  if  a  confirm  but¬ 
ton  or  trigger  was  pushed;  ALERT  NO,  if  a  cancel  button  or 
trigger  was  pushed;  ALERT_FAILED,  if  the  alert  failed  to 
pop  up;  and  ALERT_TRIGGERED,  if  a  keyboard  accelera¬ 
tor  was  used. 
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Table  19-3  Canvas  Attributes 


M'f  "  . ^ . . . . . .  ...  ■  .  ,  .  1 

Attribute 

Type 

Description 

CANVAS_AUTO_CLEAR 

boolean 

If  TRUE,  repaint  area  of  canvas  pixwin  is  cleared  before, 
repaint  proc  is  called.  Default:  TRUE  unless  the  canvas  is  retained. 

CANVAS_AUTO_EXPAND 

boolean 

If  TRUE,  canvas  width  and  height  are  never  allowed  to  be 
less  than  the  edges  of  the  canvas  pixwin.  Default:  TRUE. 

CANVAS_AUTO_SHRINK 

boolean 

If  TRUE,  canvas  width  and  height  are  never  allowed  to  be 
greater  than  the  edges  of  the  canvas  pixwin.  Default  TRUE. 

CANVAS_FAST_MONO 

boolean 

If  TRUE,  tells  canvases  and  graphics  subwindows  to  use 

the  monochrome  overlay  plane  of  the  Sun-3/110  display.  Default:  FALSE. 

CANVAS_F IXED_IMAGE 

boolean 

If  TRUE,  canvas  package  assumes  that  client  is  drawing  a  fixed-size  image 
whose  rendering  does  not  dqjend  on  the  size  of  the  canvas.  Default:  TRUE. 

CANVAS_HEIGHT 

int 

Height  of  object  being  drawn.  Default  height  of  usable  window,  which  is 

WIN  HEIGHT  -  (SCROLL_THICKNESS  of  WIN_HORI ZONTAL_SCROLLBAR)  - 
CANVAS_MARGIN*2. 

CANVAS_MARGIN 

int 

Margin  to  leave  around  the  canvas  pixwin  firom  inside  of  window.  Default:  0. 

CAWAS_PIXWIN 

Pixwin  * 

Pixwin  for  drawing.  Get  only. 

CANVAS_REPAINT_PROC 

(procedure) 

Called  when  repaint  needed,  even  if  retained.  Default:  NULL.  Form: 
repaint_proc (canvas,  pixwin,  repaint_area) 

Canvas  canvas; 

Pixwin  *pixwin; 

Rectlist  *repaint_area; 

CANVAS_RES I ZE_PROC 

(procedure) 

Called  when  canvas  width  or  height  changes.  Default  NULL.  Form: 
resize  proc (canvas,  width,  height) 

Canvas  canvas; 

int  width; 

int  height; 

CANVAS_RETAINED 

boolean 

If  TRUE,  image  is  backed  up  for  repaint  Default:  TRUE. 

CANVAS_WIDTH 

int 

Width  of  object  being  drawn.  Default:  width  of  usable  window,  which  is 

WIN  WIDTH  -  (SCROLL_THICKNESS  of  WIN_VERTICAL_SCROLLBAR)  - 
CANVAS_MARGIN*2. 
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T able  19-4  Canvas  Functions  and  Macros 

Definition 

Description 

Event  * 

canvas  event (canvas,  event) 

Canvas  canvas; 

Event  * event; 

Translates  the  coordinates  of  event  from  the  space  of  the 

canvas  subwindow  to  the  space  of  the  logical 

canvas  (which  may  be  larger  and  scrollable).  That  is, 

the  client  passes  in  a  pointer  to  an  event,  then  the 

function  does  an  event  set  x  (event,  translated  x) 

and  an  event_set_y (event,  translated_y) . 

It  then  returns  the  same  pointer  that  was 
passed  in. 

Pixwin  * 

canvas  pixwin (canvas) 

Canvas  canvas; 

Returns  the  pixwin  to  use  when  drawing  into 
the  canvas  with  the  pw  *  ( )  routines. 

Event  * 

canvas  window  event (canvas,  event) 

Canvas  canvas; 

Event  * event; 

Translates  the  coordinates  of  event  to  the  space  of  the 
canvas  subwindow  from  the  space  of  the  logical 

canvas. 
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Table  19-5  Cursor  Attributes 


Attribute 

Value  Type 

Description 

CURSOR_CROSSHAIR_BORDER_GRAVITY 

boolean 

Crosshairs  stick  to  borders.  Default:  FALSE. 

CURSOR_CROSSHAIR_COLOR 

int 

Color  for  crosshairs.  Default:  1.  (Note:  the  color  displayed 
depends  on  the  settings  in  your  colormap  segment). 

CURSOR_CROSSHAI R_GAP 

int 

Half-length  of  space  to  leave  untouched  from  intersection  of 
crosshairs.  Value  of  CURSOR  TO  EDGE  extends  crosshairs  to 
edge  of  cursor  rect.  Default:  0. 

CURSOR_CROSSHAIR_LENGTH 

int 

Half-length  of  crosshairs.  Default:  CURSOR_TO_EDGE. 

CORSOR_CROSSHAIR_OP 

int 

Raster  op  for  drawing  crosshairs.  Default:  PIX_SRC. 

CURSOR_CROSSHAIR_THICKNESS 

int 

Thickness  of  crosshairs.  Maximum  value  is 
CURSOR_MAX_HAIR_THICKNESS  (5).  Default:  1, 

CURSOR_FULLSCREEN 

boolean 

Clip  crosshairs  to  edge  of  screen  not  window.  Default:  FALSE. 

CURSOR_HORI Z_HAIR_BORDER_GRAVI TY 

boolean 

Horizontal  crosshair  sticks  to  borders.  Default:  FALSE. 

CURSOR_HORI  Z_HAIR__COLOR 

int 

See  CURSOR_HORIZ_HAIR__COLOR 

CURSOR_HORI Z_HAIR_GAP 

int 

See  CURSOR_CROSSHAIR_GAP. 

CURSOR_HORI Z_HAIR_LENGTH 

int 

See  CURSOR_CROSSHAIR_LENGTH. 

CURSOR_HORIZ_HAIR_OP 

int 

Raster  op  for  drawing  horizontal  crosshair.  Default:  P  IX_SRC. 

CURSOR_HORIZ_HAIR_THICKNESS 

int 

See  CURSOR_CROSSHAIR_THICKNESS. 

CURSOR_IMAGE 

Pixrect  * 

Cursor’s  image.  Default:  16x16x1  blank  pixrecL 

CURSOR_OP 

int 

Raster  op  for  drawing  cursor  image. 

Default:  PIX_SRC  |  PIX_DST. 

CURSOR_SHOW_CROSSHAIRS 

boolean 

Show  or  don’t  show  crosshairs.  Default:  FALSE. 

CURSOR_SHOW_CURSOR 

boolean 

Show  or  don’t  show  cursor  image.  Default:  TRUE. 

CURSOR_SHOW_HORI Z_HAIR 

boolean 

Show  or  don’t  show  horizontal  crosshair.  Default;  FALSE. 

CURSOR_SHOW_VERT_HAIR 

boolean 

Show  or  don’t  show  vertical  crosshair.  Default:  FALSE. 
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Table  19-5 

Cursor  Attributes —  Continued 

Attribute 

Value  Type 

Description 

CURSOR_VERT_HAI R_BORDER_GRAVI TY 

boolean 

Vertical  crosshair  sticks  to  borders.  Default:  FALSE. 

CURSOR_VERT_HAIR_COLOR 

int 

See  CURSOR_CROSSHAIR_COLOR 

CURSOR_VERT_HAIR_GAP 

int 

See  CURSOR_CROSSHAIR_GAP, 

CURSOR_VERT_HAIR_LENGTH 

int 

See  CURSOR_CROSSHAIR_LENGTH. 

CURSOR_VERT_HAIR_OP 

int 

Raster  op  for  drawing  vertical  crosshair.  Default:  FIX  SRC. 

CURSOR_VERT_HAIR_THI CKNES  S 

int 

See  CURSOR_CROSSHAIR_THICKNESS. 

CURSOR_XHOT 

int 

Hot  spot  X  coordinate.  Default:  0. 

CURSOR_YHOT 

int 

Hot  spot  y  coordinate.  Default  0. 

o 
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Table  19-6  Cursor  Functions 


. •=■■■ 

Definition 

Description 

Cursor 

cursor  copy (src_cursor) 

Cursor  src_cursor; 

Creates  and  returns  a  copy  of  src_cursor. 

Cursor 

cursor  create (attributes) 

<attribute-list>  attributes; 

Creates  and  returns  the  opaque  handle  to  a  cursor. 

void 

cursor_destroy (cursor) 

Cursor  cursor; 

Destroys  cursor. 

caddr  t 

cursor  get (cursor,  attribute) 

Cursor  cursor; 

Cursor  attribute  attribute; 

Retrieves  the  value  for  an  attribute  of  cursor. 

void 

cursor  set  (cursor,  attributes) 

Cursor  cursor; 

<attribute-list>  attributes; 

Sets  the  value  for  one  or  more  attributes  of  cursor. 

attributes  is  a  null-terminated  attribute  list. 
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_ Data  Type 

Canvas 

Cursor 

Destroy_status 

Event 


Frame 

Icon 

Inputmask 

Menu 

Menu_attribute 

Menu_generate 

Menu_item 
Notify_arg 
Notif y_destroy 

Notif y_event 


_ Description _ 

Pointer  to  an  opaque  structure  which  describes  a  canvas. 

Pointer  to  an  opaque  structure  which  describes  a  cursor. 

Enumeration:  DESTROY_PROCESS_DEATH, 

DESTROY_CHECKING,  or  DESTROY_CLEANUP. 

The  structure  which  desa-ibes  an  input  event: 
typedef  struct  inputevent  { 
short  ie_code; 
short  ie_flags; 
short  ie_shiftmask; 
short  ie_locx; 
short  ie_locy; 
struct  timeval  ie_time; 

}  Event; 

Pointer  to  an  opaque  structure  which  describes  a  frame. 

Pointer  to  an  opaque  structure  which  describes  a  icon. 

Mask  specifying  which  input  events  a  window  will  receive. 

Pointer  to  an  opaque  structure  which  describes  a  menu. 

One  of  the  menu  attributes  (MENU_*). 

Enumerated  type  of  the  operation  parameter  passed  to  generate  procs: 

MENU_CREATE,  MENU_DESTROY,  MENU_NOTIFY_CREATE  or  MENU_NOTIFY_DESTROY. 

Pointer  to  an  opaque  stmcture  which  describes  a  menu  item. 

Opaque  cHent  optional  argument. 

Enumeration:  NOTIFY_SAFE,  NOTIFY_IMMEDIATE. 

(See  also  Notify_event_type). 

Opaque  client  event. 
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Table  19-7 

Data  Types —  Continued 

Data  Type 

Description 

Notify  error 

Enumeration  of  errors  for  notifier  functions: 

NOTIFY  OK,  NOTIFY_UNKNOWN_CLIENT,  NOTIFY_NO_CONDITION, 

NOTIFY  BAD  ITIMER,  NOTIFY_BAD_SIGNAL,  NOTIFY_NOT_STARTED, 

NOTIFY  DESTROY_yETOED,  NOTIFY_INTERNAL_ERROR,  NOTIFY_SRCH, 

NOTIFY  BADF,  NOTIFY_NOMEM,  NOTIFY_INVAL,  or  NOTIFY_FUNC_LIMIT. 

Notif y_event_type 

Enumeration:  NOTIFY_SAFE,  NOTIFY_IMMEDIATE. 

Notify_f unc 

Notifier  function. 

Notify  signal_mode 

Enumeration:  NOTIFY_SYNC,  NOTIFY_ASYNC. 

Notify  value 

Enumeration  of  possible  return  values  for  client  notify  procs: 

NOTIFY  DONE,  NOTIFY_IGNORED,  or  NOTIFY_UNEXPECTED. 

Panel 

Pointer  to  an  opaque  structure  which  describes  a  panel. 

P  a  ne  l__at  t  r  ibu  t  e 

One  of  the  panel  attributes  (PANEL_*). 

Panel_item 

Pointer  to  an  opaque  structure  which  describes  a  panel  item. 

Panel  setting 

Enumerated  type  returned  by  panel_text_not  if  y  ( ) ; 
also  type  of  repaint  argument  to  panel_paint  {) . 

See  the  Panels  chapter  and  <suntool  /panel .  h>. 

Pixf ont 

The  structure  representing  a  font  (for  definition  see  the  Pixrect  Reference  Manual). 

Pixrect 

The  basic  object  of  pixel  manipulation  in  the  SunView  window  system.  Pixrects 
include  both  a  rectangular  array  of  pixels  and  the  means  of  accessing  operations 
for  manipulating  those  pixels  (for  definition  see  the  Pixrect  Reference  Manual). 

Pixwin 

The  basic  imaging  element  of  the  SunView  window  system.  While,  for 
historical  reasons,  its  fields  are  public,  clients  should  treat  it  as  an  opaque  handle. 

Rect 

The  structure  describing  a  rectangle: 
typedef  struct  rect  { 
short  r_left; 
short  r_top; 
short  r_width; 
short  r  height; 

}  Rect ; 
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Data  Type 


Re ct list 


Description 


A  list  of  rectangles: 
typedef  struct  rectlist  { 
short  rl_x,  rl_y; 
Rectnode  *rl_head; 
Rectnode  *rl_tail; 

Rect  rl_bound; 

}  Rectlist; 


typedef  struct  rectnode  { 
Rectnode  *rn_next; 

Rect  rn_rect ; 

}  Rectnode; 


Scroll  motion 


Scrollbar 


Scrollbar  attribute 


Scrollbar_setting 


Textsw 


Textsw  index 


Enumerated  type  representing  possible  scrolling  motions: 
SCROLL_ABSOLaTE,  SCROLL_FORWARD,  SCROLL_MAX_TO_POINT, 
SCROLL_PAGE_FORWARD,  SCR0LL_LINE_F0RWARD, 
SCROLL_BACKWARD,  SCROLL_POINT_TO_MAX, 
SCROLL_PAGE_BACKWARD,  or  SCROLL_LINE_BACKWARD. 

The  opaque  handle  for  a  scrollbar. 

One  of  the  scrollbar  attributes  (SCR0LL_*). 

The  value  of  an  enumerated  type  scrollbar  attribute. 

Pointer  to  an  opaque  structure  which  desoribes  a  text  subwindow. 

An  index  for  a  character  within  a  text  subwindow. 


Textsw  enum 


Textsw  status 


Window 


Enumerated  type  for  various  text  subwindow  attribute  values: 

TEXTSW_ALWAYS,  TEXTSW_NEVER,  TEXTSW_0NLY, 
TEXTSW_IF_AUTO_SCROLL,  TEXTSW_CLIP, 

TEXTSW_WRAP_AT_CHAR,  TEXTSW_WRAP__AT_WORD. 

Enumeration  describing  the  status  of  text  subwindow  operations: 
TEXTSW_STATUS_OKAY,  TEXTSW_STATUS_BAD_ATTR, 

TEXTSW__STATUS_BAD_ATTR_VALaE,  TEXTSW_STATUS_CANNOT_ALLOCATE, 
TEXTSW_STATUS_CANNOT_OPEN_INPUT,  or  TEXTSW_STATUS_OTHER_ERROR, 

Pointer  to  an  opaque  structure  which  describes  a  tty  subwindow. 

Pointer  to  an  opaque  structure  which  describes  a  window. 


osun 


microsysterns 


Revision  A,  of  May  9, 1988 


Chapter  19  —  SunView  Interface  Summary  {Data  Types)  327 


Table  19-7 

Data  Types —  Continued 

Data  Type 

Description 

Window_attribute 

One  of  the  window  attributes  (WIN_*). 

Window_type 

Type  of  window,  retrieved  via  the  WIN_TyPE  attribute.  One  of: 

FRAME  TYPE,  PANEL  TYPE,  CANVAS_TYPE,  TEXTSW_TYPE,  or  TTY_TYPE. 
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Table  19-8  Icon  Attributes 


Type 

Description 

ICON_FONT 

Pixfont  * 

Font  for  icon’s  label. 

ICON_HEIGHT 

int 

Icon’s  height  in  pixels.  Default:  64. 

ICON_IMAGE 

Pixrect  * 

Memory  pixrect  for  icon’s  image. 

I CON_IMAGE_RECT 

Reel  * 

Rect  for  icon’s  image.  Default:  origin  (0,  0),  width  64,  height  64. 

ICON_LABEL 

char  * 

Icon’s  label. 

I CON_LABEL_RECT 

Reel  * 

Rect  for  icon’s  label.  Default:  origin  (0, 0),  width  0,  height  0. 

ICON_WIDTH 

int 

Icon’s  width  in  pixels.  Default:  64. 
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Table  19-9  Icon  Functions  and  Macros 


V  .t.  .  ^  .  .»L1.  .  .  .  .  . ^ 


Definition 

Description 

Icon 

icon  create (attributes) 

<attribute-list>  attributes; 

Creates  and  returns  the  opaque  handle  to  an  icon. 

int 

icon  de s t roy (icon) 

Icon  icon; 

Destroys  icon. 

caddr  t 

icon  get (icon,  attribute) 

Icon  icon; 

Icon  attribute  attribute; 

Retrieves  the  value  for  an  attribute  of  icon. 

int 

icon  set (icon,  attributes) 

Icon  icon; 

<attribute~list>  attributes; 

Sets  the  value  for  one  or  more  attributes  of  icon. 

attributes  is  a  null-terminated  attribute  list. 

extern  static  struct  mpr_data 

DEFINE  ICON_FROM_IMAGE (name,  image) 
static  short  icon_iniage  [  ]  ; 

Macro  that  creates  a  static  memory  pixrect 
icon  from  image;  the  latter  typically  is  gen¬ 
erated  by  including  a  file  created  by  i  conedi  t . 

Note:  you  must  pass  the  address  of  i  con  to  the 
icon  routines,  since  the  I  con  object  is  a  pointer. 
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Table  19-10 

Event  Codes 

■*  .  •*  *'  .  ^ 

Event  Code 

Description 

Value  (for  debugging) 

ASCI I_FIRST 

Marks  beginning  of  ASCII  range 

0 

ASCII_LAST 

Marks  end  of  ASCII  range 

111 

META_FIRST 

Marks  beginning  of  META  range 

128 

META_LAST 

Marks  end  of  META  range 

255 

ACTI ON_ERASE_CHARJBACKWARD 

Erase  char  to  the  left  of  caret 

31744 

ACTI ON_ERASE_CHAR_FORWARD 

Erase  char  to  the  right  of  caret 

31745 

ACTI ON_ERASE_WORD_BACKWARD 

Erase  word  to  the  left  of  caret 

31746 

ACTION_ERASE_WORD_FORWARD 

Erase  word  to  the  right  of  caret 

31747 

ACTION_ERASE_LINE_BACKWARD 

Erase  to  the  beginning  of  the  line 

31748 

ACT ION_ERASE_LI NE_END 

Erase  to  the  end  of  the  line 

31749 

ACTION_GO_CHAR_BACKWARD 

Move  the  caret  one  character  to  the  left 

31752 

ACTI ON_GO_CHAR_FORWARD 

Move  the  caret  one  character  to  the  right 

31753 

ACTI ON_GO_WORD_BACKWARD 

Move  the  caret  one  word  to  the  left 

31754 

ACTION_GO_WORD_END 

Move  the  caret  to  the  end  of  the  word 

31756 

ACTI ON_Gq_WORD_FORWARD 

Move  the  caret  one  word  to  the  right 

31755 

ACTI ON_Gq_LINE_BACKWARD 

Move  the  caret  to  the  start  of  the  line 

31757 

ACTI OW_GO_LI NE_END 

Move  the  caret  to  the  end  of  the  line 

31759 

ACTI ON_GO_LI NE_FORWARD 

Move  the  caret  to  the  start  of  the  next  line 

31758 

ACTI ON_GO_COLUMN_BACKWARD 

Move  the  caret  up  one  line, 
maintaining  column  position 

31761 

ACTION_GO_COLUMN_FORWARD 

Move  the  caret  down  one  line, 
maintaining  column  position 

31762 

ACTION_GO_DOCUMENT_START 

Move  the  caret  to  the  beginning  of  the  text 

31763 

ACT I ON_GO_DOCUMENT_END 

Move  the  caret  to  the  raid  of  the  text 

31764 

ACTION_STOP 

Stop  the  operation 

31767 

ACTION_AGAIN 

Repeat  previous  operation 

31768 

ACTION_PROPS 

Show  property  sheet  window 

31769 

ACTION_UNDO 

Undo  previous  operation 

31770 

ACTION_FRONT 

Bring  window  to  the  front  of  the  desktop 

31772 

ACTION_BACK 

Put  the  window  at  the  back  of  the  desktop 

31773 

ACTION_OPEN 

Open  a  window  from  its  icon  form  or  close 
if  already  open) 

31775 

ACTION_CLOSE 

Close  a  window  to  an  icon 

31776 

ACTION_COPY 

Copy  the  selection  to  the  cHpboard 

31774 

ACTION_PASTE 

Copy  clipboard  contents  to  the  insertion  point 

31777 

ACTION_CUT 

Delete  the  selection,  put  on  clipboard 

31781 

ACTION_COPY_THEN_PASTE 

Copies  then  pastes  text 

31784 

ACTION_FIND_FORWARD 

Find  the  text  selection  to  the  right  of  the  caret 

31779 

ACTI 0N_F IND_BACKWARD 

Find  the  text  selection  to  the  left  of  the  caret 

31778 

ACTI ON_FIND_AND_REPLACE 

Show  find  and  replace  window 

31780 

ACTION_SELECT_FIELD_FORWARD 

Select  the  next  delimited  field 

31783 
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Table  19-10  Event  Codes —  Continued 


Event  Code 

Description 

Value  (for  debugging) 

ACTION_SELECT_FIELD_BACKWARD 

Select  the  previous  delimited  field 

31782 

ACTION_MATCH_DELIMITER 

Selects  text  up  to  a  matching  delimiter 

31894 

ACTION_QUOTE 

Causes  next  event  in  the  input  stream  to 
pass  untranslated  by  the  keymapping  system 

31898 

ACTION  EMPTY 

Causes  the  subwindow  to  be  emptied 

31899 

ACTION  STORE 

Stores  the  specified  selection  as  a  new  file 

31785 

ACTION  LOAD 

Loads  the  specified  selection  as  a  new  file  ^ 

31786 

ACTION  GET  FILENAME 

Gets  the  selected  filename 

31788 

ACTION  SET  DIRECTORY 

Sets  the  directory  to  the  selection 

31788 

ACTION_INCLUDE_FILE 

Selects  the  current  line  (in  pending-delete  mode) 
and  attempts  to  insert  the  file  described  by  that  selection 

31891 

ACTI ON_CAP  S_LOCK 

Toggle  caps  lock  state 

31895 

PANEL  EVENT_CANCEL 

The  panel  or  panel  item  is  no  longer  “current” 

32000 

PANEL_EVENT_MOVE_IN 

The  panel  or  panel  item  was  entered 
with  no  mouse  buttons  down 

32001 

PANEL  EVENT  DRAG  IN 

The  panel  or  panel  item  was  entoed  with  one  or  more 

32002 

mouse  buttons  down 

SCROLL_REQUEST 

Scrolling  has  been  requested 

32256 

SCROLL  ENTER 

Locator  (mouse)  has  moved  into  the  scrollbar 

32257 

SCROLL_EXIT 

Locator  (mouse)  has  moved  out  of  the  scrollbar 

32258 

LOC  MOVE 

Locator  (mouse)  has  moved 

32512 

LOC  STILL 

Locator  (mouse)  has  bear  stiU  for  1/5  second 

32513 

LOC  WINENTER 

Locator  (mouse)  has  entered  window 

32514 

LOC  WINEXIT 

Locator  (mouse)  has  exited  window 

32515 

LOC  DRAG 

Locator  (mouse)  has  moved  while  a  button  was  down 

32516 

LOC  RGNENTER 

Locator  (mouse)  has  entered  a  region  of  the  window 

32519 

LOC  RGNEXIT 

Locator  (mouse)  has  exited  a  region  of  the  window 

32520 

LOC  TRAJECTORY 

Inhibits  the  collapse  of  mouse  motions;  clients  receive 

32523 

LOC  TRAJECTORY  events  for  every  locator  motion 
the  window  system  detects. 

WIN_REPAINT 

Some  portion  of  window  requires  repainting 

32517 

WIN  RESIZE 

Window  has  been  resized 

32518 

WIN_STOP 

User  has  pressed  the  stop  key 

32522 

KBD  REQUEST 

Window  is  about  to  become  the  focus  of  keyboard  input 

32526 

KBD  USE 

Window  is  now  the  focus  of  keyboard  input 

32524 

KBD  DONE 

Window  is  no  longer  the  focus  of  keyboard  it^ut 

32525 

SHIFT  LEFT  Left  shift  key  changed  state 

SHI FT_RI GHT  Right  shift  key  changed  state 

SHIFT  CTRL  Control  key  changed  state 

SHIFT  META  Meta  key  changed  state 

SHIFT  LOCK  Shift  lock  key  changed  state 
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Table  19-10 

Event  Codes —  Continued 

Event  Code 

Description 

Value  (for  debugging) 

SHIFT_CAPSLOCK 

Caps  lock  key  changed  state 

32528 

BUT(i) 

Locator  (mouse)  buttons  1-10 

BUT(l)  is  32544 

MS_LEFT 

Left  mouse  button 

32544 

MS_MIDDLE 

Middle  mouse  button 

32545 

MS_RIGHT 

Right  mouse  button 

32546 

KEY_LEFT (i) 

Left  function  keys  1-15 

KEY_LEFT(1)  is  32554 

KEY_RIGHT{i) 

Right  function  keys  1-15 

KEY_RIGHT  (1 }  is  32570 

KEY_TOP (i) 

Top  function  keys  1-15 

KEY_TOP  (1)  is  32586 
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Table  19-11  Event  Descriptors 


> 


Event  Descriptor 

Explanation 

WIN_NO_EVENTS 

Clears  input  mask  —  no  events  will  be  accepted.  Note:  the 
effect  is  the  same  whether  used  with  a  consume  or  an 
ignore  attribute.  A  new  window  has  a  cleared  input  mask. 

WIN_ASC I I_EVENT S 

All  ASCn  events.  ASCII  events  that  occur  while  the  META 
key  is  depressed  are  reported  with  codes  in  the  META  range. 

In  addition,  cursor  control  keys  and  function  keys  are 
reported  as  ANSI  escape  sequences:  a  sequence  of  events 
whose  codes  are  ASCII  characters,  beginning  with  <ESC>. 

WIN_IN_TRANSIT_EVENTS 

Enables  immediate  LOG  MOVE,  LOC_WINENTER,  and 

LOG  WINEXIT  events.  Pick  mask  only.  Off  by  default. 

WIN_LEFT_KEYS 

The  left  function  keys,  KEY_LEFT(1)  —  KEY_LEFT(15>. 

WIN_MOUSE_BDTTONS 

Shorthand  for  MS_RIGHT,  MS_MIDDLE  and  MS_LEFT. 

Also  sets  or  resets  WIN  UP_EVENTS. 

WIN_RIGHT_KEYS 

The  right  function  keys,  KEY_RIGHT(1)  —  KEY_RIGHT(15). 

WIN_TOP_KEYS 

The  top  function  keys,  KEY_TOP(l)  —  KEY_TOP(15), 

WIN_UP_ASCI I_EVENTS 

Causes  the  matching  up  transitions  to  normal 

ASCn  events  to  be  reported  —  if  you  see  an  ’a’ 
go  down,  you’ll  eventually  see  the  matching  ’a’  up. 

WIN_OP_EVENTS 

Causes  up  transitions  to  be  reported  for  button 

- 

and  fimction  key  events  being  consumed. 
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Table  19-12 

Input-Related  Window  Attributes 

^  '  y  '  ^ 

Attribute 

Value  Type 

Description 

WIN_INPUT_DESIGNEE 

int 

Window  which  gets  events  this  window  doesn’t  consume. 

(Note  that  the  value  must  be  the  designee’s  WIN_DEVICE_NUMBER). 

WIN_GRAB_ALL_INPDT 

boolean 

Window  will  get  all  events  regardless  of  location. 

WIN_KBD_FOCUS 

boolean 

Whether  or  not  the  window  has  the  keyboard  focus. 

WIN_KBD_INPUT_MASK 

Inputmask  * 

Window’s  keyboard  inputniask. 

WI N_P ICK_INP  UT_MASK 

Inputmask  * 

Window’s  pick  inputmask. 

WIN_CONSUME_KBD_EVENT 

short 

Window  will  receive  this  event. 

WIN_IGNORE_KBD_EVENT 

short 

Window  will  not  receive  this  event 

WI N_CONSDME_KBD_E VENTS 

short  list 

Null  terminated  list  of  events  window  will  receive. 

WIN_IGNORE_KBD__EVENTS 

short  list 

Null  terminated  list  of  events  window  will  not  receive. 

WI N_CON SUME_P ICK_E VENT 

short 

Window  will  receive  this  pick  event. 

WIN_IGNORE_PICK_EVENT 

short 

Window  will  not  receive  this  pick  event 

WIN_CONSDME_PICK_EVENTS 

short  list 

Null  terminated  list  of  pick  events  window  will  receive. 

WIN_IGNORE_PICK_EVENTS 

short  list 

Null  terminated  list  of  pick  events  window  will  not  receive. 
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Table  19-13  Menu  Attributes 


Attribute 

Value  Type 

Description 

MENU_ACT I ON_IMAGE 

Pixrect  *,  action  proc 

Create  image  menu  item  with  action  proc.  Set  only. 

MENU_ACT I ON_I TEM 

char  *,  action  proc 

Create  string  menu  item  with  action  proc.  Set  only. 

MENU_APPEND_I TEM 

Menu_item 

Append  item  to  end  of  menu.  Set  only. 

MENU_BOXED 

boolean 

If  TRUE,  a  single-pixel  box  will  be  drawn  around 
every  menu  item. 

MENU_CENTER 

boolean 

If  TRUE,  aU  string  items  in  the  menu  will  be  centered.  Default  FALSE 

MENU_CL IENT_DATA 

caddr_t 

For  client’s  use. 

MENU_COLUMN_MAJOR 

boolean 

If  TRUE,  string  items  in  the  menu  will  be  sorted  in  column-major 
order  (like  ls(l))  instead  of  row-major  order.  Default  FALSE 

MENU_CLIENT_DATA 

caddr_t 

For  client’s  use. 

MENU_DESCEND_F IRST 

(no  value) 

For  menu_f  ind  ( ) .  If  given,  search  will 
be  depth  first,  else  search  will  be  "deferred". 

MENU_DEFADLT 

int 

Default  menu  item  as  a  position. 

MENU_DEFAULT_I TEM 

Menu_item 

Default  menu  item  as  opaque  handle. 

MENU_DEFAULT_SELECT I ON 

enum 

Either  MENU_SELECTED  or  MENU_DEFAULT. 

MENU_FIRST_EVENT 

Evoit  * 

The  event  which  was  initially  passed  into 
menu_show  ( ) .  Get  only. 

(Note  that  the  event’s  contents  can  be  modified.) 

MENO_FONT 

Pixfont  * 

Menu’s  font. 

MENU__GEN_PROC 

(procedure) 

Client’s  function  called  to  generate  the  menu. 

Menu  gen_j>roc  (m,  op) 

Menu  m; 

Menu  generate  op; 

MENU_GEN_POLLRIGHT_IMAGE 

Pixrect  *,  gen  proc 

Create  image  menu  item  with 
generate  proc  for  pullright.  Set  only. 

MENU_GEN_P  ULLRI GHT_I TEM 

char  *,  gen  proc 

Create  string  menu  item  with 
generate  proc  for  pullright  Set  only. 

MENU_IMAGE_ITEM 

Pixrect  *,  value 

Create  image  menu  item  with  value.  Set  only. 
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T able  19-13  Mem  Attributes —  Continued 


Attribute 


Value  Type 


Description 


MENU  IMAGES 


list  of  Pixrect  * 


Create  multiple  image  menu  items.  Set  only. 


MENU  INITIAL  SELECTION 


Either  MENU  SELECTED  or  MENU  DEFAULT. 


MENU  INITIAL  SELECTION  EXPANDED  boolean 


K  TRUE,  when  the  menu  pops  up,  it 
automatically  e}q)an(is  to  select  the  initial  selection. 


MENU  INITIAL  SELECTION  SELECTED  boolean 


If  TRUE,  menu  comes  up  with  its  initial 
selection  highlighted.  If  FALSE,  menu  comes 
up  with  the  cursor  "standing  off  to  the  left 


MENU  INSERT 


int,  Menu_item 


Insert  new  itan  after  nth  item.  Set  only. 


MENU  INSERT  ITEM 


Menu_item,  Menu_item  The  item  given  as  the  second  value  is  inserted 
after  the  one  given  as  the  first  value.  Set  only. 


MENU  ITEM 


Create  a  mam  item  inline  —  avlist  same  as  for 
menu  create  itemf).  Set  only. 


MENU  JUMP  AFTER  NO  SELECTION  boolean 


If  TRUE,  cursor  jumps  back  to  its 
original  position  after  no  selection  made. 


MENU  JUMP  AFTER  SELECTION 


boolean 


If  TRUE,  cursor  jumps  back  to  its 
original  position  after  selection  made. 


MENU  LAST  EVENT 


Event  * 


The  last  event  read  by  the  menu.  Get  only. 
Note  that  the  event’s  contaits  can  be  modified. 


MENU  LEFT  MARGIN 


For  each  string  item,  margin  in  addition  to 
MENU_MARGIN  on  left  between  menu’s 
border  and  text  Default:  16. 


MENU  MARGIN 


Margin  in  pixels  around  menu  items.  Default:  1. 


MENU  NCOLS 


Number  of  colmnns  in  menu. 


MENU  NITEMS 


Get  only;  returns  the  #  of  items  in  the  menu. 


MENU  NROWS 


Number  of  rows  in  menu. 


MENU  NOTIFY  PROC 


(procedure) 


Client’s  function  called  when  the  user  selects 
a  menu  item. 

caddr_t  notify_jproc  (m,  mi) 

Menu  m; 

Menu  item  mi; 
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Table  19-13 

Menu  Attributes —  Continued 

Attribute 

Value  Type 

Description 

MENU_NTH_1TEM 

int 

starting  &om  1. 

Get  only;  returns  nth  menu  item,  n  is  counted 

MENU_PARENT 

Menu_item 

The  menu  item  for  which  the  menu  is  a  puUright.  Get  only. 

MENU_PULLRI GHT_DELTA 

int 

Number  of  pixels  the  user  must  move  the  cursor 
to  the  right  to  cause  a  puUright  menu  to  pop  up. 

Default:  9999. 

MENU_PULLRIGHT_IMAGE 

Pixrect  *,  Mmu 

Create  image  menu  item  with  puUright.  Set  only. 

MENU_P  ULLRI GHT_I TEM 

char  *,  Menu 

Create  string  mmu  item  with  puUrighL  Set  only. 

MENU_REMOVE 

int 

Remove  the  nth  item.  Set  only. 

MENO_REMOVE_I TEM 

Menu_item 

Remove  the  specified  item.  Set  only. 

MENU_REPLACE 

int,  Menu_item 

Replace  nth  item  with  specified  item.  Set  only. 

MEND_REPLACE_I TEM 

Menu_item,  Menu_ 

item  The  item  given  as  first  value  is  replaced 
with  the  one  given  as  the  second  value 
in  the  menu  (the  old  item  is  not  replaced 
in  any  other  menus  it  may  appear  in).  Set  only. 

MENU_RIGHT_MARGIN 

int 

For  each  string  item,  margin  in  addition  to 

MENO_MARGIN  on  right 
between  menu’s  border  and  text. 

MEND_SELECTED 

int 

Last  selected  item,  as  a  position  in  menu. 

MENU_SELECTED_ITEM 

Menu_item 

Last  selected  item,  as  the  item’s  handle. 

MENU_SHADOW 

Pixrect  * 

Pattern  for  the  shadow  to  be  painted  behind 
the  menu.  If  0,  no  shadow  is  painted. 

Predefined  shadow  pixrects  you  can  use; 
menu  gray25^r,  menu  gray50_pr, 
and  menu  gray75_pr. 

MENU_STAY_UP 

boolean 

If  TRUE  the  first  click  of  the  Menu  button  puts  up  the  menu,  the 
second  takes  it  down;  in  between,  the  menu  stays  up.  Default  FALSE 

MENU_STRINGS 

list  of  char  * 

Create  multiple  string  menu  items.  Set  only. 

MENU_STRI NG_I TEM 

char  *,  value 

Create  string  menu  item  with  value.  Set  only. 
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Table  19-13  Menu  Attributes — Continued 


Attribute  Value  Type  Description 


MENU__TITLE_IMAGE 

Pixrect  * 

Create  image  title  item.  Set  only. 

MENU_TITLE_ITEM 

char* 

Create  string  title  item.  Set  only. 

MENU_TYPE 

enum 

Get  only;  returns  MENU  MENU. 

MENU_VALI D_RESULT 

boolean 

Tells  whether  a  zero  return  value  represents  a  legitimate  value. 
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Table  19-14  Mem  Item  Attributes 


Attribute 

. . . 

Description 

MENU_ACTI ON_IMAGEt 

Pixrect  *,  action  proc 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_ACTION_ITEMt 

char  *,  action  proc 

Modifies  appropriate  fields  in  item.  Set  only. 

MENO_ACT I ON_PROC 

(procedure) 

Client’s  function  called  after  item  has  been  selected: 
caddr_t  action_proc (menu,  menu  item) 

Menu  menu 

Menu_item  menu_item 

MENU_APPEND_I TEMf 

Menu_item 

Append  item  to  end  of  menu.  Set  only. 

MENU_BOXEDt 

boolean 

If  TRUE,  a  single-pixel  box  wiU  be  drawn  around  the  item. 

MENU_CENTERt 

boolean 

If  TRUE,  the  menu  item  will  be  centered  on  its  row  in  the  menu. 
Only  meaningful  for  menu  strings. 

MENU_CL IENT_DATAt 

caddr_t 

For  use  by  the  client. 

MENU_FEEDBACK 

boolean 

If  FALSE,  item  is  never  inverted  and  is  not  selectable. 

MENU_FONTt 

Pixfont  * 

Item’s  font. 

MENU_GEN_PROCt 

(procedure) 

Client’s  procedure  called  to  generate  the  item. 

MENU_GEN_PROC_IMAGE 

Pixrect  *,  (procedure) 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_GEN_PROC_I TEM 

char  *,  (procedure) 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_GEN_PULLRIGHT 

generate  proc 

Generate  proc  for  the  item’s  pullright. 

MENU_GEN_PULLRIGHT_ 

IMAGEt 

Pixrect  *,  (procedure) 

Modifies  apfffopriate  fields  in  item.  Set  only. 

MEND_GEN_PULLRIGHT_ 

I  TEMf 

char  *,  gen  proc 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_IMAGE 

Pixrect  * 

Item’s  image. 

MENU_IMAGE_I TEMf 

char  *,  action  proc 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_INACTIVE 

boolean 

If  TRUE,  item  is  grayed  out  and  not  selectable. 

t  Many  of  the  attributes  in  this  table  appeared  in  the  previous  table.  Menus  and  menu  items  have  many  attributes  in  common.  Attributes  marked  with 
‘t”  are  also  valid  for  menus,  although  the  effect  of  the  attribute  may  differ. 


wsun 

XT  microsystems 


Revision  A,  of  May  9,  1988 


340  SunView  1  Programmer’s  Guide 


Table  19-14  Menu  Item  Attributes —  Continued 


Attribute 

Value  Type 

Description 

MENU__INVERT 

boolean 

If  TRUE,  item’s  display  is  inverted. 

MENU_LEFT_MARGINt 

int 

Margin  in  addition  of  MENU  MARGIN  on  left  between 
menu’s  border  and  text. 

MENU_MARGINt 

int 

Margin  in  pixels  around  the  item. 

MENU_PARENTt 

Menu 

The  menu  containing  the  item. 

MENU_PULLRIGHT 

Menu 

Item’s  pullright  menu. 

MENU_P  ULLRI GHT_I MAGEf 

Pixrect  *,  Menu 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_P  ULLRI GHT_I TEMf 

char  *,  Menu  . 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_RELEASE 

(no  value) 

The  item  will  be  automatically  destroyed  when  its  parent 
menu  is  destroyed  (default  for  items  created  inline). 

MENU  RELEASE_IMAGE 

(no  value) 

The  string  or  pixrect  associated  with  the  item  will  be 
freed  when  the  item  is  destroyed. 

MENU_RI  GHT_MARGINt 

int 

Margin  in  addition  of  MENU_MARGIN  on  right  between 
mom’s  border  and  text 

MENU_SELECTEDt 

boolean 

If  TRUE,  the  item  is  currently  selected. 

MENU_STRINGt 

char  * 

Item’s  string. 

MENU_STRI NG_I TEMf 

char  *,  value 

Modifies  appropriate  fields  in  item.  Set  only. 

MENU_TYPEt 

enum 

Get  only,  returns  MENU_ITEM. 

MENU_VALUE 

caddr_t 

Item’s  value. 
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Table  19-15  Menu  Functions 

Definition 

Description 

Menu 

menu_create (attributes) 

<attribute-list>  attributes;  ' 

Creates  and  returns  the  opaque  handle  for  a  walking  menu. 

Menu  item 

menu  create  item  (attributes) 

<attribute-Ust>  att  ribut  e  s  ; 

Creates  and  returns  the  opaque  handle  for  a  single  item 
within  a  walking  menu. 

void 

menu  destroy (menu  object) 

<Menu  or  Menu_item>  menu_ob  j  ect ; 

Destroys  a  mmu  or  menu  item. 

void 

menu  destroy  with  proc (menu  object,  destroy  proc) 
<Menu  or  Menu_item>  menu_ob  j  ect ; 
void  (*destroy_proc)  ()  ; 

The  function  supplied  as  destroy_proc  is  called  before 
the  menu  or  menu  item  is  destroyed.  Arguments: 
destroy__proc  (menu  object,  type) 

<MenuorMenu  tte»c>menu  object; 

Menu_at tribute  type; 
type  is  MENU  MENU  for  menus,  MENU  ITEM  for  items. 

Menu  item 

men u_find (menu,  attributes) 

Menu  menu ; 

<attribute~list>  attributes; 

Returns  the  first  menu  item  in  menu  meeting  the  criteria 
specified  in  attributes. 

caddr_t 

menu_get (menu_object ,  attribute [,  optional  arg] ) 
<MenuorMenu  item>  menu  object; 

Menu  attribute  attributes; 
caddr_t  optional_arg; 

Retrieves  the  value  for  an  attribute  of  a  menu  or  menu  item. 

int 

menu_set (menu  object,  attributes) 

<Menu or Menu_item>  menu  object; 

<attribute-list>  att  ribute  s  ; 

Sets  the  value  of  one  or  more  attributes  for  a  menu  or  menu. 

item,  attributes  is  a  null-terminated  attribute  list. 

caddr  t 

men u_show (menu,  window,  event,  0) 

Menu  menu ; 

Window  window; 

Event  * event; 

Displays  the  menu,  gets  a  selection  from  the  user,  and,  by 
default,  returns  the  value  of  the  item  the  user  has  selected. 

window  is  the  handle  of  the  window  over  which  the  menu 
is  displayed;  event  is  the  event  which  causes  the  menu  to 
come  up.  The  final  argument  is  currently  ignored. 
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Table  19-15  Menu  Functions — 

Continued 

Definition 

Description 

caddr  t  menu  show  using_fd (menu,  fd,  event) 

Menu  menu; 

Provided  for  compatibility  with  SunWindows  2.0.  Allows 

int  fd; 

you  to  display  a  menu  within  a  window  using  the  windowfd. 

Event  *  event ; 

caddr  t 

Predefined  notify  proc  which,  if  given  as  the  value  for 

menu  return  item (menu,  menu_item) 

MEND  NOTIFY  PROC,  causes  menu_show  ( )  to  return 

Menu  menu; 

the  handle  of  the  selected  item,  rather  than  its  value. 

Menu^item  menu_item; 

caddr_t 

menu  return_value (menu,  menu_item) 

Default  notify  proc  for  menus.  Causes  menu_show  ( ) 

Menu  menu; 

to  return  the  value  of  the  selected  item. 

Menu  item  menu  item; 
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Table  19-16  Notifier  Functions 


Definition 

Description 

Notify  value 

notify_default_wait3 (client,  pid, 
Notify_client  client; 
int  pid; 

union  wait  *status; 

struct  rusage  *rusage; 

status,  rusage) 

Predefined  function  you  can  register  with  the  Notifier  via  the 
notify_set_wait3_func  0  call.  Causes  the  required 
housekeeping  to  be  performed  on  the  process  identified  by  pid 
when  it  dies.  See  the  wait (2)  man  page  for  details  of  the 
wait  and  rusage  structures. 

Notify_error 
notify_dispatch {) 

Provided  to  allow  programs  which  are  not  notification-based  to 
run  in  the  SunView  environment.  Called  regularly  from  within 
the  ai5)Iication’s  main  loop  to  allow  the  Notifier  to  go  once 
around  its  internal  loop  and  dispatch  any  pending  events. 

Not i f y_error 
notify_do  dispatch {) 

Called  once,  before  the  application’s  main  loop.  Enables 
“implicit  dispatching,”  in  which  the  Notifier  dispatches 
events  firom  within  calls  to  read(2)  or  select(2). 

Notify_error 

notify_interpose_destroy_func (client,  destroy  func) 
Notify  client  client; 

Notify_func  destroy_func; 

Interposes  destroy_f  unc  ( )  in  front  of 
client’s  destroy  qvent  handler. 

Notify_error 

notify_interpose  event  func (client 

event 

Notify  client  client; 

Notify_func  event  func; 

Notify_event_type  type; 

r 

func,  type) 

Interposes  event_f  unc  ( )  in  front  of 
client’s  event  handler. 

Notify_error 

notify_itimer_value (client,  which, 
Notify_client  client; 

int  which; 

struct  it  interval  *  value; 

value) 

Returns  the  current  state  of  an  interval  timer  for  cl  lent  in  the 
structure  pointed  to  by  value.  The  which  parameter 
is  either  ITIMER_REAL  or  ITIMER_VIRTUAL. 

Notify  value 

nc>tify_next_destroy_func  (client,  status) 
Notify_client  client; 

Destroy  status  status; 

Calls  the  next  destroy  event  handler  for  client, 
status  returns  DESTROY_PROCESS_DEATH, 
DESTROY_CHECKING,  or  DESTROY_CLEANUP. 
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Table  19-16  Notifier  Functions —  Continued 


Definition 

Description 

Notify_value 
notify  next_event_ 

func (client,  event,  arg,  type) 

Notify_client 

client; 

Calls  the  next  evrait  handler  for  client. 

Event 

* event; 

Notify  arg 

arg; 

Notify  event  type  type; 

Notify  error 

Prevents  the  Notifier  from  dispatching  events  from  within  the 

notify  no_dispatch 0 

call  to  read(2)  or  select(2). 

void 

Analogous  to  the  UNIX  perror(3)  system  call. 

notify  perror(s) 

s  is  printed  to  s  tderr,  followed  by  a  terse  description  of 

char  *s; 

notify_errno  () . 

Notify_func 

Registers  destroy  func  ( )  with  the  Notifier. 

notify  set  destroy_func (client ,  destroy_func) 

destroy  func()  will  be  called  when  a 

Notify_client 

client; 

destroy  event  is  posted  to  client  or  when  the  process 

Notify_func 

de  s t  roy_f unc ; 

receives  a  SIGTERM  signal. 

Notify  func 

Registers  the  exception  handler  except  ion_f  unc  ( ) 

notify  set  exception_func  (client,  exception_func,  fd) 

with  the  Notifier.  The  only  known  devices  that  generate 

Notify_client 

cl lent ; 

exceptions  at  diis  time  are  stream-based  socket 

Notify_func 

except ion_f unc; 

connections  when  an  out-of-band  byte  is  available. 

int 

fd; 

Notify_func 

notify  set  input_func (client ,  input_func,  fd) 

Registers  input_f  unc  ( )  with  the  Notifier. 

Notify_client 

client; 

input  func  ( )  will  be  called  whenever 

Notify_func 

input_f unc ; 

there  is  input  pending  on  f  d. 

int 

fd; 

Notify_func 
notify  set  it  inter 

func  (client,  itimer_func,  which. 

Registers  the  timeout  event  handlCT  itimer_func  () 

value,  ovalue) 

with  the  NotifiCT.  The  semantics  of  which,  value 

Notify  client 

client; 

and  ovalue  parallel  the  arguments  to  setitimer 

Notify  func 

itimer  func; 

(see  the  getitimer  manual  page). 

int 

which; 

which  is  either  ITIMER_REAL  or  ITIMER_VIRTUAL. 

struct  itimerval  *value,  *oyalue; 
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Table  19-16  Notifier  Functions — Continued 


Definition 

Description 

Notify_func 

notify_set_signal 

_func (client,  signal  func. 

signal,  when) 

Registers  the  signal  event  handler  signal  func  ( )  with 

Notify  client 

client; 

the  Notifier.  signal_f  unc  ( )  will  be  called  whenever 

Notify  func 

signal_func; 

signal  is  caught  by  the  Notifier.  when  can  be  either 

int 

signal; 

NOTIFY_SYNC  or  NOTIFY_ASYNC. 

Notify_signal_ 

mode  when; 

Calling  notify_set_signal_func  ()  with  a  NULL  in  the 
place  of  the  signal_func  ()  turns  off  checking  for  that 
signal  for  that  client. 

Notify  error 
notify_start  () 

Begins  dispatching  of  events  by  the  Notifier. 

Notify_error 
notify  stopO 

Terminates  dispatching  of  events  by  the  Notifier. 

Notify_func 
notify_set  output_ 

func  (client,  output  func,  fd) 

Registers  output_func  ()  with  the  Notifier. 

Notify_client 

client; 

output_f  unc  ( )  will  be  called  whenever 

Notify_func 

output  func; 

output  has  been  completed  on  f  d. 

int 

fd; 

Notify_func 

Registers  the  function  wait3_f  unc  ( )  with  the  Notifier. 

notify_set_wait3_func {client ,  wait3  func,  pid) 

The  registered  function  wiU  be  called  after  the  child 

Notify  client 

client; 

process  identified  by  pi  d  dies.  To  do  the  minimum 

Notify_func 

wait 3  func; 

processing,  register  the  predefined  function 

int 

pid; 

notify_default_wait3 0 . 

Notify  error 

Called  from  within  a  destroy  evait  handler  when  status 

notify_veto  destroy (client) 

is  DESTROY  CHECKING  and  the  application  does  not 

Notify  client 

client; 

want  to  be  destroyed. 
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Table  19-17  Panel  Attributes 


Attribute 

Value  Type 

Description 

PANEL_ACCEPT_KEySTROKE 

boolean 

If  TRUE,  keystroke  events  are  passed 

to  the  panel’s  PANEL_BACKGROUND_PROC.  Default  FALSE. 

PANEL_BACKGROUND_PROC 

(procedure) 

Event  handling  procedure  called  when  an 
event  falls  on  the  backgroimd  of  the  panel.  Form: 
background  pro c (panel,  event) 

Panel  panel 

Event  * event 

PANEL_BLINK_CARET 

boolean 

If  TRUE,  the  caret  blinks.  Default  setting  of  5/tn/:_carer  in  the  Text 
category  of  def  aultsedit. 

PANEL_CARET_I TEM 

Panel_item 

Text  itan  which  currently  has  the  caret. 

Default  first  text  item. 

PANEL_EVENT_PROC 

(procedure) 

Event  handling  procedure  for  panel  items. 

Sets  the  default  for  subsequent  items  created  in  panel.  Form: 
event_proc (item,  event) 

Panel_item  item 

Event  * event 

PANEL_FIRST_ITEM 

Panel_item 

First  item  in  the  panel.  Get  only. 

PANEL_I TEM_X_GAP 

int 

Niunber  of  x-pixels  between  items.  Default  10. 

PANEL_ITEM_Y_GAP 

int 

Number  of  y-pixels  between  items.  Default  5. 

PANEL_LABEL_BOLD 

boolean 

If  TRUE,  item’s  label  is  rendered  in  bold. 

Sets  the  default  for  subsequent  items  created  m  panel.  Default:  FALSE. 

PANEL_LAYOUT 

Panel_setting 

Layout  of  item’s  value  relative  to  the  label. 

PANEL_HORIZONTAL  (default)  or  PANEL_VERTICAL. 

PANEL_SHOW_MENU 

boolean 

If  TRUE,  th6  menu  for  the  itan  is  enabled. 

Sets  the  default  for  subsequent  items  created  in  panel. 
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T able  19-18  Generic  Panel  Item  Attributes 


Attribute 

Value  Type 

Description 

P ANEL_ACCEP  T_KEy STROKE 

boolean 

If  TRUE,  keystroke  events  are  passed  to  the  item’s  EVENT  PROG. 

PANEL_CLIENT_DATA 

caddr_t 

For  application’s  use. 

PANEL_EVENT_PROC 

(procedure) 

Event  handling  procedure  for  the  item. 

PANEL_I TEM_RECT 

Rect  * 

Enclosing  rectangle  for  the  item.  Get  only. 

PANEL_ITEM_X 

int 

Left  edge  of  item  rectangle.  If  unspecified  and  label  or  value  positions  are 
fixed,  then  set  to  min  of  PANEL_LABEL_X  and  PANEL_VALUE_X. 
Default:  after  lowest,  rightmost  item 

PANEL_ITEM_Y 

int 

top  edge  of  item  rectangle.  If  unspecified  and  label  or  value  positions  are 
fixed,  then  set  to  min  of  PANEL_LABEL_Y  and  PANEL_VALUE_Y. 
Default:  previous  item’s  PANEL_ITEM_Y. 

PANEL_LABEL_X 

int 

Left  edge  of  label.  If  unspecified  and  value  position  is  fixed,  then  set  to 
left  of  PANEL_VALUE_X  for  horizontal  layout,  or  at  PANEL_VALUE_X 
for  vertical  layout.  Default:  PANEL_ITEM_X. 

PANEL_LABEL_Y 

int 

Top  edge  of  label.  If  unspecified  and  value  position  is  fixed,  flien  set  to 
PANEL_VALUE_Y  for  horizontal  layout,  or  above  PANEL  VALUE  Y 
for  vertical  layout  Default:  PANEL_ITEM_Y. 

PANEL_LABEL_BOLD 

boolean 

If  TRUE,  item’s  label  is  rendered  in  bold.  Default  FALSE. 

PANEL_LABEL_FONT 

Pixfont  * 

Font  for  PANEL_LABEL_STRING.  Default  WIN_FONT. 

PANEL_LABEL_IMAGE 

Pixrect* 

Image  for  item’s  label. 

PANEL_LABEL_STRING 

char  * 

String  for  item’s  label. 

PANEL_LAYOUT 

Panel_settmg 

Layout  of  item’s  value  relative  to  the  label.  PANEL_HbRI  ZONTAL 
(default)  or  PANEL_VERTICAL. 

PANEL_MEND_CHOICE_FONTS 

hst  of  Pixfont  * 

Font  for  each  menu  choice  string.  Create,  set.  Default  WIN  FONT. 

PANEL_MENU_CHOICE_IMAGES 

list  of  Pixrect  * 

Image  for  each  menu  choice.  Create,  set  Default 
PANEL_CHOICE_IMAGES  for  choice  items,  PANEL_LABEL_IMAGE 
for  button  items,  NULL  for  otho*  items. 

PANEL_MENU_CHOICE_STRINGS 

list  of  char  * 

String  for  each  menu  choice.  Create,  set  Default 

PANEL  CHOICE  STRINGS  for  choice  items,  NULL  for  other  items. 

PANEL_MENa_CHOICE_VALUES 

list  of  caddr_t 

The  values  returned  firom  the  item’s  menu.  Create,  set 
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Table  19-18  Generic  Panel  Item  Attributes —  Continued 


Attribute 

Value  Type 

Description 

PANEL_MENU_TITLE_FONT 

Pixfont  * 

Font  for  PANEL_MENU_TITLE_STRING. 

PANEL_MENU_TITLE_IMAGE 

Pixrect  * 

Image  for  the  menu  title. 

PANEL_MENU_TITLE_STRING 

char  * 

String  for  the  menu  title. 

PANEL_NEXT_ITEM 

Panel_item 

Next  item  in  the  panel.  Get  only. 

PANEL_NOTIFY_PROC 

(procedure) 

Function  to  call  when  item  is  selected.  Form  for  button  and  text  items: 
notify  proc(item,  event) 

Panel  item  item 

Event  * event 

Choice  and  slider  items  have  an  additional  parameter  for  die  current  value: 
notify_proc (item,  value,  event) 

Panel_item  item 
int  value 

Event  * event 

For  toggle  items,  die  value  parameter  is  of  type  unsigned  int. 

The  type  for  a  text  item  notify_j>roc  is  Panel_setting. 

PANEL_PAINT 

Panel_settmg 

Item’s  painting  behavior  for  panel_set  ( )  caUs.  One  of: 

PANEL_NONE,  PANEL_CLEAR,  or  PANE L_NO_C LEAR 

PANEL_PARENT_PANEL 

Panel 

The  panel  which  contains  the  item. 

PANEL_SHOW_ITEM 

boolean 

Whether  or  not  to  show  the  item.  Default:  TRUE. 

PANEL_SHOW_MENU 

boolean 

If  TRUE,  the  menu  for  the  item  is  enabled. 

PANEL_VALUE_X 

int 

Left  edge  of  value.  If  unspecified  and  label  position  is  fixed, 
then  set  to  right  of  PANEL_LABEL_X  for  horizontal  layout,  or 
at  PANEL  LABEL  X  for  vertical  layout.  Default:  after  the  label. 

PANEL_VALDE_Y 

int 

Top  edge  of  value.  If  unspecified  and  label  position  is  fixed,  then  set 
to  PANEL  LABEL  Y  for  horizontal  layout,  or  below 

PANEL  LABEL  Y  for  vertical  layout.  Default:  PANEL_LABEL_Y. 
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Table  19-19  Choice  and  Toggle  Item  Attributes 


. '■■■: . ; . ; . 

. ^ . . 

Attribute 

Value  Type 

Description 

PANEL_CHOICE_FONTS 

list  of  Pixfont  * 

Font  to  use  for  each  choice  string.  Create,  set. 

P ANEL_CHO I CE_I MAGE 

int,  pixrect  * 

Image  for  choice  specified  by  the  first  argument. 

PANEL_CHOICE_IMAGES 

list  of  Pixrect  * 

Image  for  each  choice.  Create,  set. 

PANEL_CHOICE_STRING 

int,  char  * 

String  for  choice  specified  by  first  argument 

PANEL_CHOICE_STRINGS 

list  of  char  * 

String  for  each  choice.  Note  that  you  must  specify  at 
least  one  choice  —  the  least  you  can  specify  is  a  single 
null  string  (PANEL_CHOICE_STRINGS ,  "  " ,  0). 

Create,  set 

PANEL_CHO ICE_X 

int,  int 

Second  argument  is  left  edge  of  choice  specified  by  first 
argument 

PANEL_CHOICE_XS 

list  of  int 

Left  edge  of  each  choice.  Create,  set. 

PANEL_CHOICE_Y 

int,  int 

Second  argument  is  top  edge  of  choice  specified  by  first 
argument 

P ANEL_CHO I CE_YS 

list  of  int 

Top  edge  of  each  choice.  Create,  set 

PANEL_CHOICES_BOLD 

boolean 

If  TRUE,  choices  strings  are  in  bold.  Default:  FALSE. 

P ANEL_D I SPLAY_LEVEL 

Panel_setting 

How  many  choices  to  display.  One  of  PANEL  NONE, 
PANEL_CURRENT,  or  PANEL_ALL.  Default: 

PANEL_ALL. 

PANEL_FEEDBACK 

Panel_setting 

Feedback  to  give  when  a  choice  is  selected.  One  of 
PANEL_NONE,  PANEL_MARKED, 

PANEL_INVERTED.  If  PANEL_DISPLAY_LEVEL  is 
PANEL_CURRENT,  default  is  PANEL_NONE,  otherwise 
PANEL_MARKED. 

PANEL_LAYOUT 

Panel_setting 

Layout  of  the-choices:  PANEL_HORIZONTAL  (default) 
or  PANEL_VERTICAL. 

PANEL_MARK_IMAGE 

int,  Pixrect  * 

Image  to  mark  choice  specified  by  the  first  argument 
when  it  is  selected.  Default  is  push-button  image: 
<images/panel  choice  on.pr>. 
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Table  19-19  Choice  and  Toggle  Item  Attributes—  Continued 


Attribute 

Value  Type 

Description 

PANEL_MARK_IMAGES  , 

list  of  Pixrect  * 

Image  to  mark  each  choice  with  when  selected.  Create, 
set  only.  Default  is  push-button  image: 

<images/panel  choice_on .pr>. 

PANEL_MARK_X 

int,  int 

Second  argument  is  left  edge  of  choice  mark  specified  by 
first  argument. 

PANEL_MARK__XS 

list  of  int 

Left  edge  of  each  choice  mark.  Create,  set. 

PANEL_MARK_Y 

int,  int 

Second  argument  is  top  edge  of  choice  mark  specified  by 
first  argument. 

PANEL_MARK_YS 

list  of  int 

Top  edge  of  each  choice  mark.  Create,  set. 

PANEL  MENU_MARK_IMAGE 

Pixrect  * 

Image  to  mark  each  menu  choice  with  when  selected. 

PANEL_MENU_NOMARK_I MAGE 

Pixrect  * 

Image  to  mark  each  menu  choice  with  when  not  selected. 

PANEL_NOMARK_IMAGE 

int,  Pixrect  * 

Image  to  mark  choice  specified  by  the  first  argument 
when  it  is  not  selected.  Default  is  push-button  image: 
<images/panel_choice_of f .pr>. 

PANEL_NOMARK_IMAGES 

list  of  Pixrect  * 

Image  to  mark  each  choice  with  when  not  selected. 

Create,  set.  Default  is  push-button  image: 
<images/panel_choice_of f . pr>. 

PANEL_SHOW_MENU_MARK 

boolean 

Show  or  don’t  show  the  menu  mark  for  each  selected 
choice.  Default:  TRUE, 

PANEL_TOGGLE_VALUE 

int,  int 

Value  of  a  particular  toggle  choice.  Second  argument  is 
value  of  choice  specified  by  first  argument 

PANEL_VALUE 

int  or  unsigned 

If  item  is  a  choice,  value  is  ordinal  position  (from  0)  of 
current  choice.  If  item  is  a  toggle,  value  is  a  bitmask 
indicating  currently  selected  choices  (e.g.,  bit  5  is  1  if 

5th  choice  selected). 
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Table  19-20  Slider  Item  Attributes 


Attribute 

Value  Type 

Description 

PANEL_MI N_VALUE 

int 

Minimum  value  of  slider.  Default:  0. 

PANEL_MAX_VALOE 

int 

Maximum  value  of  the  slider.  Default:  100. 

PANEL_NOTIFY_LEVEL 

Panel_setting 

When  to  call  the  notify  function:  PANEL_DONE  notifies  when  the 
select  button  is  released,  PANEL_ALL  notifies  continuously  as  the 
select  button  is  dragged.  Default:  PANEL  DONE. 

PANEL_SHOW_RANGE 

boolean 

Show  or  don’t  show  the  min  and  max  slider  values.  Default:  TRUE. 

PANEL_SHOW_VALUE 

boolean 

Show  or  don’t  show  integer  value  of  slider.  Default:  TRUE. 

PANEL_SLIDER_WI DTK 

int 

Width  of  the  slider  bar  in  pixels.  Default:  100. 

PANEL_VALUE 

int 

Initial  or  new  value  for  the  item,  in  the  range 

PANEL_MIN_VALUE  to  PANEL_MAX_VALUE.  Default: 
PANEL_MIN_VALUE. 

PANEL_VALUE_FONT 

Pixfont  * 

Font  to  use  when  displaying  the  value. 
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Table  19-2 1  Text  Item  Attributes 


Attribute 

Value  Type 

Description 

PANEL_MASK_CHAR 

char 

Character  used  to  mask  type-in  characters.  Use  the  space  character 
for  no  character  echo  (caret  does  not  advance).  Use  the  null  char¬ 
acter  to  disable  masking. 

PANEL_NOT IFY_LEVEL 

Panel_settmg 

When  to  call  the  notify  function.  One  of  PANEL_NONE, 

P2tNEL  NON_PRINTABLE,  PANEL_SPECIFIED,  or 

PANEL  ALL.  Default:  PANEL_SPECIFIED  (see  Text 
Notification). 

PANEL_NOTIFY_STRING 

char  * 

String  of  characters  which  trigger  notification  when  typed. 

Applira  only  when  PANEL_NOTIFY_LEVEL  is 

PANEL  SPECIFIED.  Default:  \n\r\t  (newline,  carriage  return 
and  tab). 

PANEL_VALUE_STORED_LENGTH 

int 

Max  number  of  characters  to  store  in  die  value  string.  Default  80. 

PANEL_VALUE_DI SPLAY_LENGTH 

int 

Max  number  of  characters  to  display  in  the  panel.  Default  80. 

PANEL_VALUE 

char  * 

Initial  or  new  string  value  for  the  item. 

PANEL  VALDE_FONT 

Pixfont  * 

Font  to  use  for  the  value  string. 
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Table  19-22  Panel  Functions  and  Macros 


Definition 

Description 

panel_accept_key (object ,  event) 

<Panel  or  Panel_item>  object; 

Event  *event; 

Action  fimction  which  tells  a  text  item  to  accept  a  keyboard  event. 
Currently  ignored  by  non-text  panel  items. 

panel_accept_menu (object,  event) 

<Panel  or  Panel_item>  object; 

Event  * event; 

Action  function  which  tells  an  item  to  display  its  menu  and  process 
the  user’s  selection. 

panel_accept_preview (object, 
<Panel  or Panel_item>  object ; 
Event  *event; 

event ) 

Action  function  which  tells  an  item  to  do  what  it  is  siqjposed  to  do 
when  it  is  selected.  This  may  include  completing  feedback 
initiated  by  panel_begin_preview  () . 

Panel_item 

panel_advance_caret  (panel ) 
Panel  panel; 

Advance  the  caret  to  the  next  text  item.  If  on  the  last 
text  item,  rotate  back  to  the  first.  Returns  the  new 
caret  item,  or  NULL  if  th»e  are  no  text  items. 

Panel  item 

panel_backup_caret (panel) 
Panel  panel; 

Backup  the  caret  to  the  previous  text  item.  If  cm  the 
first  text  item,  rotate  back  to  the  first  Returns  the 
new  caret  item,  or  NULL  if  there  are  no  text  items. 

panel_begin_j>review (object,  event) 

<Panel  or  Paneljtem>  object ; 

Event  *event ; 

Action  function  which  tells  an  item  to  begin  any  feedback  which 
indicates  tentative  selection. 

Pixrect  * 

panel_button_image (panel,  string,  width,  font) 
Panel  panel; 
char  * string; 
int  width; 

Pixfont  *font; 

Creates  a  standard,  button-like  image  from  a  string.  The  string  is 
rendered  in  font,  centered  within  a  double-pixel  border  width 
characters  wide.  If  width  is  too  narrow  for  the  string,  the  border 
will  be  expanded  to  contain  the  entire  string.  If  font  is  0, 
panel’s  font  is  used. 

panel_cancel_preview (object, 
<Panel  or  Panel jtem>  object ; 
Event  * event; 

event ) 

Action  function  which  tells  an  item  to  cancel  the  feedback  initiated 
by  panel_begin_preview  () . 

Pane l_i tern 

panel_create_item (panel,  item 
Panel  panel; 

<item  type>  item_type; 
<attribute-list>  attributes; 

_type,  attributes) 

Creates  and  returns  the  opaque  handle  to  a  panel  item,  item  type 
is  one  of;  PANEL_MESSAGE,  PANEL_BUTTON,  PANEL_CHOICE, 
PANEL_CYCLE,  PANEL_TOGGLE,  PANEL_TEXT  or 
PANEL_SLIDER.  attributes  is  a  null-terminated  attribute  list. 
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Table  19-22  Panel  Functions  and  Macros—  Continued 


Definition 

Description 

panel_default_handle_event (object,  event) 
<Panel  or Panel_iteni>  object  ; 

Event  *event; 

The  default  event  proc  for  panel  items  (PANEL_EVENT_PROC) 
and  for  the  panel’s  background  (PANEL_BACKGROUND_PROC). 
Implements  the  standard  event-to-action  mapping  for  the  item  types. 

panel  destroy_item(item} 

Panel_item  item; 

Destroys  item. 

panel  each_item (panel,  item) 

Panel  panel; 

Panel_item  item; 

Macro  to  iterate  over  each  item  in  a  panel.  The  corresponding  macro 
panel_end_each  closes  the  loop  opened  by 
panel_each_item ( ) . 

Event  * 

panel  event (panel,  event) 

Panel  panel; 

Event  *  event ; 

Translates  the  coordinates  of  event  from  the  space  of  the  panel 
subwindow  to  the  space  of  the  logical  panel 
(which  may  be  larger  and  scrollable). 

caddr_t 

panel  get (item,  attribute [,  optional_arg] ) 
Panel_item  item; 

Panel  attribute  attribute; 

Panel_attribute  optional_arg; 

Retrieve  the  value  of  an  attribute  for  item.  optional_arg  is 
used  for  a  few  attributes  which  require  additional  information, 
such  as  PANEL_CHOICE_IMAGE,  PANEL_CHOICE_STRING, 
PANEL_CHOICE_X,  PANEL_CHOICE_Y, 

PANEL_MARK_X,  PANEL_MARK_Y,  PANEL_TOGGLE_VALUE. 

caddr_t 

panel_get_value (item) 

Panel_item  item; 

A  macro,  defined  as: 

panel  get (item,  PANEL_VALUE) 

panel_paint (panel_ob ject,  paint_behavior) 
<Panel  item  or  Panel>  panel_object; 

Panel  setting  paint_behavior; 

Paints  an  item  or  an  entire  panel.  paint_behavior  can  be  either 
PANEL  CLEAR  or  PANEL_NO_CLEAR.  PANEL_CLEAR  causes 
the  area  occupied  by  the  panel  or  item  to  be  cleared  prior  to  painting. 

panel  set (item,  attributes) 

Panel  item  item; 

<attribute-Iist>  attributes; 

Sets  the  value  of  one  or  more  panel  attributes, 
attributes  is  a  null-teiminated  attribute  list. 

panel  set_value (item,  value) 

Panel_item  item; 
caddr_t  value; 

A  macro,  defined  as: 

panel  set (item,  PANEL_VALDE,  value,  0) 

Panel_setting 

panel_text_notify (item,  event) 

Panel  item  item 

Event  *event 

Default  notify  procedure  for  panel  text  items.  Causes  caret 
to  advance  on  CR  or  tab,  caret  to  backup  on  shift-CR  or  shift-tab, 
jmntable  characters  to  be  inserted  into  item' s  value, 
and  all  other  characters  to  be  discarded. 
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Table  19-22  Panel  Functions  and  Macros —  Continued 


Definition 

Description 

panel_update_preview (object,'  event) 

<Panel  or  Paneljtem>  object ; 

Event  *event; 

Action  function  which  tells  the  item  to  update  its  previewing 
feedback  (e.g.  redraw  the  slider  bar  for  a  slider  item). 

panel_update_scrolling  size (panel) 

Panel  panel; 

Updates  the  scrollbar’s  notion  of  the  panel’s  size, 
so  the  scrollbar’s  bubble  will  be  the  correct  size. 

Event  * 

panel_window_event (panel,  event) 

Panel  panel; 

Event  *event; 

Translates  the  coordinates  of  event  to  the  space  of  the  panel 
subwindow  from  the  space  of  the  logical  panel 
(which  may  be  largCT  and  scrollable). 

Xr  microsystems 


Revision  A,  of  May  9, 1988 


356  SimView  1  Programmer’s  Guide 


Table  19-23  Pixwin  Drawing  Functions  and  Macros 


Definition 

Description 

pw_batch (pw,  n) 

Pixwin  *pw; 

Pw  batch  type  n; 

Tells  the  batching  mechanism  to  refresh  the  screen  every 
n  display  operations. 

pw_batch_off (pw) 

Pixwin  *pw; 

A  macro  to  turn  batching  off  in  pw. 

pw  batch_on(pw) 

Pixwin  *pw; 

A  macro  to  turn  batching  on  in  pw. 

pw_batchrop (pw,  dx,  dy,  op,  items,  n) 

Pixwin  *pw; 

int  dx,  dy,  op,  n; 

struct  pr_prpos  items []; 

See  the  Pixrect  Reference  Manual  for  a  full  explanation 
of  this  function. 

pw_char(pw,  x,  y,  op,  font,  c) 

Pixwin  *pw; 

int  X,  y,  op; 

Pixfont  *font; 

char  c; 

Writes  character  c  into  pw  using  the  rasterop  op. 

The  left  edge  and  baseline  of  c  will  be  written  at 
location  (x,  y). 

pw  close (pw) 

Pixwin  *pw; 

Frees  any  dynamic  storage  associated  with  pw, 
including  its  retained  memory  pixrect,  if  any. 

pw_copy(dpw,  dx,  dy,  dw,  dh, 
op,  spw,  sx,  sy> 

Pixwin  *dpw,  *spw; 

int  op,  dx,  dy,  dw,  dh,  sx,  sy; 

Copies  pixels  from  spw  to  dpw.  Currently  spw  and 
dpw  must  be  the  same.  This  routine  will  cause  problems  if 
spw  is  obscured. 

int 

pw_get (pw,  X,  y) 

Pixwin  *pw; 

int  X,  y; 

Returns  the  value  of  the  pixel  at  (x ,  y)  in  pw. 

int 

pw  get__region_rect  (pw,  r) 

Pixwin  *pw; 

Rect  *r; 

Retrieves  the  rectangle  occupied  by  the  region  pw 
into  the  rect  pointed  to  by  r. 
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T able  1 9-23  Pixwin  Drawing  Functions  and  Macros —  Continued 


Definition 

Description 

pw__line(pw,  xO, 

yO,  xl,  yl,  brush,  tex,  op) 

Pixwin 

*pw; 

Draws  a  solid  or  textured  line  between  two  points  with  a 

int 

xO,  yO,  xl,  yl,  op; 

“brush”  of  a  specified  width. 

struct  pr_brush  *brush; 

struct  pr_texture  *tex; 

pw  lock(pw,  r) 

Acquires  a  lock  for  the  user  process  making  the  call. 

Pixwin  *pw; 

r  is  the  rectangle  in  pw’s  coordinate  system 

Rect  *r; 

that  bounds  the  area  to  be  affected. 

pw_j>f  sysclose  () 

Closes  the  system  font  opened  with  pw_pf  sy  sopen  ( ) . 

Pixfont  * 

Opens  the  system  font. 

pw__pf  sysopen  () 

pw_polygon  2 (pw. 

dx,  dy,  nbds,  npts. 

vlist,  op,  spr,  sx,  sy) 

Pixwin 

*pw; 

int 

dx,  dy,  nbds,  op,  sx,  sy; 

Draws  a  polygon  in  pw. 

int 

npts  []  ; 

struct  pr_pos  *vlist; 

Pixrect 

*spr; 

pw_j5olyline  (pw. 

dx,  dy,  npts. 

ptlist,  mvlist,  brush,  tex,  op) 

Pixwin 

*pw; 

int 

dx,  dy,  npts,  op; 

Draws  multiple  lines  of  a  specified  width  and  texture  in 

struct  pr_pos  *ptlist; 

pw. 

u_char 

*mvlist; 

struct  pr_brush  *brush; 

struct  pr  texture  *tex; 

pw_j>olypoint  (pw. 

dx,  dy,  npts,  ptlist,  op) 

Pixwin 

int 

*pw; 

dx,  dy,  npts,  op; 

Draws  an  array  of  npts  points  in  the  pixwin  pw 

struct  pr_pos  *ptlist; 

pw_put(pw,  X,  y. 

value) 

Pixwin  *pw; 

Draws  a  pixel  of  value  at  (x ,  y)  in  pw. 

int  X,  y,  value; 
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Table  19-23  Pixwin  Drawing  Functions  and  Macros —  Continued 


Definition 

Description 

pw_read(pr,  dx,  dy,  dw,  dh,  op,  pw,  sx,  sy) 

Pixwin  *pw; 

int  op,  dx,  dy,  dw,  dh,  sx,  sy; 

Pixrect  *pr; 

Reads  pixels  from  the  pixwin  pw  starting  at  offset  (sx, 
sy),  using  rasterop  op.  The  pixels  are  stored  in  the  rec¬ 
tangle  (dx,  dy,  dw,  dh)  in  the  pixrect  pointed  to  by  pr. 

Pixwin  * 

pw_region (pw,  x,  y,  width,  height) 

Pixwin  *pw; 

int  X,  y,  w,  h; 

Creates  a  new  pixwin  refering  to  an  area  within  the  existing 
pixwin  pw.  The  origin  of  the  new  region  is  given  by  (x , 
y),  the  dimensions  by  width  and  height. 

pw_replrop  (pw,  dx,  dy,  dw,  dh, 
op,  pr,  sx,  sy) 

Pixwin  *pw; 

int  dx,  dy,  dw,  dh,  op,  sx,  sy; 

Pixrect  *pr; 

Rq)licates  a  pattern  from  a  pixrect  into  a  pixwin. 

pw_reset (pw) 

Pixwin  *pw; 

Macro  which  sets  pw’s  lock  count  to  0  and  releases  its  lock. 

pw_rop(pw,  dx,  dy,  dw,  dh, 
op,  sp,  sx,  sy) 

Pixwin  *pw; 

Pixrect  *sp; 

int  dx,  dy,  dw,  dh,  op,  sx,  sy; 

Performs  the  rasterop  op  from  the  sotorce  pixrect 
sp  to  the  destination  pixwin  pw. 

int 

pw  set  region_rect (pw,  r,  use_same_pr) 

Pixwin  *pw; 

Rect  *r; 

unsigned  int  use  same_pr; 

The  position  and  size  of  the  region  pw  are  set  to  the  rect 
*r. 

If  u  se  same_jpr  is  0  a  new  retained  pixrect  is  allocated 
for  the  region. 

pw  show(pw) 

Pixwin  *pw; 

Macro  to  refresh  the  screen  while  batching,  without  affect¬ 
ing  the  batching  mode. 

pw  stencil (dpw,  dx,  dy,  dw,  dh,  op, 

stpr,  stx,  sty,  spr,  sx,  sy) 

Pixwin  *dpw; 

int  dx,  dy,  dw,  dh,  op,  stx, '  sty,  sx,  sy; 

Pixrect  *stpr,  *spr; 

Like  pw_write  ( ) ,  excq)t  that  the  source  pixrect  spr  is 
written  through  the  stencil  pixrect  stpr,  which  functions 
as  a  spatial  write  enable  mask.  The  raster  operation  op  is 
only  applied  to  destination  pixels  where  the  stpr  is  non¬ 
zero;  other  destination  pixels  remain  unchanged. 

pw_text(pw,  X,  y,  op,  font,  s) 

Pixwin  *pw; 

int  X,  y,  op; 

Pixfont  */font; 

char  *s; 

Writes  the  string  s  into  pw  using  the  rasterop  op. 

The  left  edge  and  baseline  of  the  first  character  in  s  will 
appear  at  coordinates  (x,  y). 
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Table  19-23  Pixwin  Drawing  Functions  and  Macros —  Continued 


Definition 

Description 

pw_traprop  (pw,  dx,  dy,  t,  op,  pr,  sx,  sy) 

Pixwin  *pw; 

struct  pr  trap  t; 

Pixrect  *pr; 

int  dx,  dy,  op,  sx,  sy; 

Like  pw_rop  ( ) ,  but  operating  on  a  trapezon  rather  than  a 
rectangle. 

pw  ttext (pw,  X,  y,  op,  font,  s) 

Pixwin  *pw; 

int  X,  y,  op; 

Pixfont  *font; 

char  *s; 

Like  pw_text  ()  except  that  it  writes  “transparent”  text, 
i.e.  it  writes  the  shape  of  the  letters  without  disturbing  the 
background  behind  the  letters. 

pw  unlock (pw) 

Pixwin  *pw; 

Decrements  the  lock  count  for  pw.  If  the  lock  count  goes 
to  0,  the  lock  is  released. 

pw  vector (pw,  xO,  yO,  xl,  yl,  op,  value) 

Pixwin  *pw; 

int  op,  xO,  yO,  xl,  yl,  value; 

Draws  a  vector  of  pixel  value  from  (xO ,  y  0)  to  (xl , 
yl)in  pw  using  rasterop  op. 

pw  write  (pw,  dx,  dy,  dw,  dh, 
op,  pr,  sx,  sy) 

Pixwin  *pw; 

int  dx,  dy,  dw,  dh,  op,  sx,  sy; 

Pixrect  *pr; 

Writes  pixels  to  pw  in  the  rectangle  defined  by  dx,  dy, 
dw,  dh,  using  rasterop  op.  Pixels  to  write  are  taken  from 
the  rectangle  with  its  origin  at  sx,  sy  in  the  source  pix¬ 
rect  pointed  to  by  pr. 

Note:  this  is  an  altanative  form  of  pw_rop. 

pw  writebackground (pw,  dx,  dy,  dw,  dh,  op) 

Pixwin  *pw; 

int  dx,  dy,  dw,  dh,  op; 

Writes  pixels  with  value  zero  into  pw  using  the  rasterop  op. 
xd,  yd,  width  and  height  specify  the  rectangle  in 
pw  which  is  affected. 
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Table  19-24  Pixwin  Color  Manipulation  Functions 


Definition 

Description 

pw  blackonwhite (pw,  min,  max) 

Pixwin  *pw; 

int  min,  max; 

Sets  the  foreground  to  black,  the  background  to  white,  for  pixwin 
pw,  min  and  max  should  be  the  first  and  last  entries,  respectively, 
in  pw’s  colormap  segment. 

pw  cyclecolormap (pw,  cycles,  index,  count) 
Pixwin  *pw; 

int  cycles,  index,  count; 

Rotates  the  portion  of  pw’s  colormap  segment  starting  at  index 
for  count  entries,  rotating  those  entries  among  themselves 
cycles  times. 

pw_dbl_access (pw) 

Pixwin  *pw; 

Resets  the  window’s  data  structure  so  that  the  first  firame  will  be  ren¬ 
dered  to  the  background. 

pw  dbl__flip  (pw) 

Pixwin  *pw; 

Allows  you  to  flip  the  display. 

pw  dbl  get (pw,  attribute) 

Pixwin  *pw; 

Pw  dbl_attribute  attribute; 

Retrieves  the  value  of  the  specified  attribute. 

pw  dbl  release  0 

Pixwin  *pw; 

Signifies  the  end  of  double-buffering  by  the  window  associated  with 
the  pixwin. 

pw_dbl_set (pw,  attributes) 

Pixwin  *pw; 

<attrihute-list>  attributes; 

Sets  the  pixwin  hardware  double-buffering  attributes  in  attri¬ 
butes. 

pw_getattributes (pw,  planes) 

Pixwin  *pw; 
int  *planes; 

Retrieves  the  value  of  pw’s  access  enable  mask 
into  the  integer  addressed  by  planes. 

pw  getcmsname (pw,  cmsname) 

Pixwin  *pw; 

char  cmsname [CMS_NAMESIZE] ; 

Copies  the  colormap  segment  name  of  pw  into  cmsname. 

pw_getcolormap (pw,  index,  count, 
red,  green,  blue) 

Pixwin  *pw; 

int  index,  count; 

unsigned  char  red[],  green[],  blue[]; 

Retrieves  the  state  of  pw’s  colormap.  The  count  elements 
of  the  pixwin’s  colormap  segment  starting  at  index 
(0  origin)  are  loaded  into  the  first  count  values  in  the 
three  arrays. 
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Table  19-24  Pixwin  Color  Manipulation  Functions —  Continued 


Definition 

Description 

pw_getdefaultcms (cms,  map) 

struct  colormapseg  *cms; 
struct  cms  map  *map; 

Copies  the  data  in  the  default  colorm^p  segment  into 

the  data  pointed  to  by  cms  and  map.  Before  the  call,  the  byte  pointers 

in  map  should  be  initialized  to  arrays  of  size  256. 

pw_put attributes (pw,  planes) 

Pixwin  *pw; 
int  *planes; 

Sets  the  access  enable  mask  of  pw.  Only  those  bits  of  the  pixel 
corresponding  to  a  1  in  the  same  bit  position  of  *planes  will  be 
affected  by  pixwin  operations. 

pw_putcolormap (pw,  index,  count, 
red,  green,  blue) 

Pixwin  *pw; 

int  index,  count; 

unsigned  char  red[],  green[],  blue[3; 

Sets  the  state  of  pw’s  colormap.  The  count  elements  of  the 
pixwin’s  colormap  segment  starting  at  index  (0  origin)  are  loaded 
from  the  first  count  values  in  the  three  arrays. 

pw_reversevideo (pw,  min,  max) 

Pixwin  *pw; 

int  min,  max; 

Reverses  the  foreground  and  backgroimd  colors  of  pw 
min  and  max  should  be  the  first  and  last  entries, 
respectively,  in  the  colormap  segment 

pw  setcmsname (pw,  cmsname) 

Pixwin  *pw; 

char  cmsname [CMS_NAMESIZE] ; 

cmsname  is  the  name  that  pw  will  caUjits  window’s 

colormq}  segment  This  call  resets  the  colormap  segment  to  NULL. 

pw  whiteonblack (pw,  min,  max) 

Pixwin  *pw; 

int  min,  max; 

Sets  the  foreground  to  white,  the  background  to  black,  for  pw. 
min  and  max  should  be  the  first  and  last  entries,  respectively,  in  the 
colormap  segment. 
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Table  19-25 

Scrollbar  Attributes 

: . V . , . ■■ 

. ■■ . 
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Attribute 

Value  Type 

Description 

SCROLL_ABSOLUTE_CURSOR 

Cursor 

Cursor  to  display  on  middle  button  down. 

Default:  Right  triangle  if  vert.,  down  triangle  if  horiz. 

SCROLL_ACT I VE_CURSOR 

Cursor 

Cursor  to  display  when  cursor  is  in  bar  rect. 

Default:  Right  arrow  if  vertical,  down  arrow  if  horiz. 

SCROLL_ADVANCED_MODE 

boolean 

Whether  notify  proc  reports  all  nine  motions.  Default:  FALSE. 

SCROLL_BACKWARD_CURSOR 

Cursor 

Cursor  to  display  on  right  button  down. 

Default:  up  arrow  if  vertical,  left  arrow  if  horiz. 

SCROLL_BAR_COLOR 

Scrollbar_setting 

Color  of  bar,  SCROLL_GREY  (default)  or  SCROLL_WHITE. 

SCROLL_BAR_DI SPLAY_LEVEL 

Scrollbar_setling 

When  bar  is  displayed. 

SCROLL_ALWAYS:  always  displayed 

SCROLL_ACTIVE:  only  displayed  when  cursor  is  in  bar  rect 
SCROLL_NEVER:  never  displayed 

Default:  SCROLL_ALWAYS. 

SCROLL_BORDER 

boolean 

Whether  the  scrollbar  has  a  border. 

SCROLL_BUBBLE_COLOR 

Scrollbar_setting 

Color  of  bubble,  SCROLL_GREY  (default)  or  SCROLL_BLACK. 

SCROLL_BUBBLE_D I SPLAY_LEVEL 

ScroIlbar_setting 

When  bubble  is  displayed. 

SCROLL  ALWAYS:  always  displayed 

SCROLL_ACTIVE:  only  displayed  when  cursor  is  in  bar  rect 
SCROLL_NEVER:  never  displayed 

Default:  SCROLL_ALWAYS. 

SCROLL_BUBBLE_MARGIN 

int 

Margin  on  each  side  of  bubble  in  bar.  Default:  0. 

SCROLL_D IRECT I ON 

Scrollbar_setting 

Orientation  of  bar, 

SCROLL_VERTICAL  (default)  or  SCROLL_HORIZONTAL. 

SCROLL_END_POINT_AREA 

int 

The  distance,  in  pixels,  from  the  end  of  the  scrollbar 
that  forces  a  scroll  to  the  beginning  (or  end)  of  the  file. 

Default:  6. 

SCROLL_FORWARD_CURSOR 

Cursor 

Cursor  to  display  on  left  button  down. 

Default:  down  arrow  if  vertical,  right  arrow  if  horiz. 

SCROLL_GAP 

int 

Gap  between  lines.  Default;  current  value  of  SCROLL_MARGI  N. 
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Table  19-25 

Scrollbar  Attributes — 

Continued 

Attribute 

Value  Type 

Description 

SCROLL_HEIGHT 

int 

r  height  for  scrollbar’s  rect. 

SCROLL_LAST_VIEW_START 

int 

Offset  of  view  into  object  prior  to  scroll.  Get  only. 

SCROLL_LEFT 

int 

r_lef  t  for  scrollbar’s  rect. 

SCROLL_L INE_HEI GHT 

int 

Numba:  of  pixels  from  one  line  to  the  next. 

Default:  0. 

SCROLLjyiARGIN 

int 

Top  margin  after  scroll,  if  SCROLL_NORMALIZE  TRUE. 

Default  4. 

SCROLL_MARK 

int 

Position  (in  client  units)  undo  will  go  to.  Initial  value:  0. 

SCROLL_NOT IFY_CLIENT 

caddr_t 

Used  by  Notifier. 

SCROLL_NORMALI ZE 

boolean 

Whether  the  client  wants  normalized  scrolling.  Default  TRUE. 

SCROLL_OBJECT 

caddr_t 

Pointer  to  the  scrollable  object 

SCROLL_OBJECT_LENGTH 

int 

Length  of  scrollable  object  in  client  units.  Default:  0. 

(Value  must  be  >  0). 

SCROLL_PAGE_BUTTONS 

boolean 

Whether  the  scrollbar  has  page  buttons.  Default  TRUE. 

SCROLL_PAGE_BUTTON_LENGTH 

int 

Length  in  pixels  of  page  buttons.  Default  15. 

SCROLL_PAINT_BUTTONS_PROC 

(procedure) 

Procedure  which  paints  page  buttons: 

paint  buttons_proc (scrollbar)  ^ 

Scrollbar  scrollbar; 

Setting  the  value  to  NULL  resets  it  to  the  default  button  painting 
procedure. 

SCROLL_PIXWIN 

Pixwin* 

Pixwin  for  scrollbar  to  write  to. 

SCROLL_PLACEMENT 

Scrollbar_setting 

Placranent  of  the  bar. 

SCROLL  WEST:  vertical  bar  on  left  edge 

SCROLL  EAST:  vertical  bar  on  right  edge 

SCROLL_NORTH:  horizontal  bar  on  top  edge 

SCROLL_SOUTH:  horizontal  bar  on  bottom  edge 

Default:  SCROLL_WEST  or  SCROLL_NORTH. 

SCROLL_RECT 

Rect  * 

Rect  for  scrollbar,  including  buttons. 
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Table  19-25 

Scrollbar  Attributes— 

~  Continued 

Attribute 

Value  Type 

Description 

SCROLL_REPEAT_T IME 

ml 

The  interval,  in  tenths  of  a  second,  that  scrolling 

repeats  in.  This  attribute  is  used  only  for  the  initial  pressing  down 

of  the  mouse.  A  value  of  0  disables  repeat  scrolling.  Default:  10. 

SCROLL_REQUEST_MOT I ON 

Scroll_motion 

Scrolling  motion  requested  by  user. 

SCROLL_REQUEST_OFFSET 

int 

Pixel  offset  of  scrolling  request  into  scrollbar.  Default:  0. 

SCROLL_THICKNESS 

int 

Thickness  of  bar.  Default:  14. 

SCROLL_TO_GRID 

boolean 

Whether  the  client  wants  scrolling  aligned  to  multiples 
of  SCROLL_LINE_HEIGHT.  Default:  FALSE. 

SCROLL_TOP 

int 

r  top  for  scrollbar’s  rect. 

SCROLL_VIEW_LENGTH 

int 

Length  of  viewing  window,  in  client  imits.  Default:  0. 

SCROLL_VIEW_START 

int 

Current  offset  into  scrollable  object  (client  units). 

(Value  must  be  >0).  Default:  0. 

SCROLL_WIDTH 

int 

r  width  for  scroUbar’s  rect 
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Table  19-26  Scrollbar  Functions 


Definition 

Description 

Scrollbar 

scrollbar_create (attributes) 

<attribute-list>  attributes; 

Creates  and  returns  the  opaque  handle  to  a  scrollbar. 

int 

scrollbar_destroy (scrollbar) 

Scrollbar  scrollbar; 

Destroys  scrollbar. 

caddr  t 

scrollbar__get  (scrollbar,  attribute) 

Scrollbar  scrollbar; 

Scrollbar_attribute  attribute; 

Retrieves  the  value  for  an  attribute  of  scrollbar. 

int 

scrollbar_set (scrollbar,  attributes) 

Scrollbar  scrollbar; 

<attribute-list>  attributes; 

Sets  the  value  for  one  or  more  attributes  of  scrollbar. 

attributes  is  a  null-terminated  attribute  list. 

void 

scrollbar  scroll  to (scrollbar,  new  view  start) 

Scrollbar  scrollbar; 
long  new  view  start; 

For  programmatic  scrolling.  Effect  is  as  if  the  user  had 
requested  a  scroll  to  new_view_start  in  the  subwin¬ 
dow  to  which  scrollbar  is  attached. 

int 

scrollbar  j)aint (scrollbar) 

Scrollbar  scrollbar; 

Paints  those  portions  of  scrollbar 
(page  buttons,  bar  proper,  and  bubble) 
which  have  been  modified  since  they  were  last  painted. 

int 

scrollbar_paint  clear (scrollbar) 

Scrollbar  scrollbar; 

Clears  and  repaints  all  portions  of  scrollbar. 

int 

scrollbar_clear_bubble (scrollbar) 

Scrollbar  scrollbar; 

Clears  the  bubble  in  scrollbar. 

int 

scrollbar__paint_bubble  (scrollbar) 

Scrollbar  scrollbar; 

Paints  the  bubble  in  scrollbar. 
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Table  19-27  Text  Subwindow  Attributes 


Attribute 

Value  Type 

Description 

TEXTSW  ADJOST_IS_PENDING_DELETE 

boolean 

When  TRUE,  adjusting  a  selection  causes  the  selection  to  be 
pending-delete.  Default:  FALSE. 

TEXTSW_AGAI N_RECORD ING 

boolean 

When  FALSE,  changes  made  to  the  textsw  are  not  repeated  when  user 
invokes  AGAIN.  By  disabling  when  not  needed  (e.g.  for  program- 
driven  error  logs)  you  can  reduce  manory  overhead.  Default:  TRUE. 

TEXTSW_AUTO_INDENT 

boolean 

When  TRUE,  a  new  line  is  automatically  indented  to  match 
the  previous  line.  Default:  FALSE. 

TEXTSW_AUTO_SCROLL_BY 

int 

Number  of  lines  to  scroll  when  type-in  moves  insert  point 
below  the  view.  Default:  1.  Create,  get. 

TEXTSW_BLINK_CARET 

boolean 

Determines  whether  the  caret  blinks.  Default:  TRUE. 

TEXTSW_BROWSING 

boolean 

When  TRUE,  prevents  editing  of  the  displayed  text.  If  another 
file  is  loaded  in,  browsing  stays  on.  Default:  FALSE. 

TEXTSW_CHECKPOINT_FREQOENCY 

int 

Number  of  edits  between  checkpoints.  Set  to  0  to 
disable  checkpointing.  Default:  0. 

TEXTSW_CLIENT_DATA 

char  * 

Pointer  to  arbitrary  client  data.  Default:  NULL. 

TEXTSW__CONF  IRM_OVERWRITE 

boolean 

A  request  to  write  to  an  existing  file  wiU  require  user 
confirmation.  Default:  TRUE. 

TEXTSW_CONTENTS 

char* 

Contents  of  text  subwindow.  Default:  NULL. 

For  create  and  set,  specifies  the  initial  contents  for  non-file  textsw. 

Get  needs  additional  parameters: 

window  get  {textsw,  TEXTSW_CONTENTS,  pos,  buf,  buf_len) 
Return  value  is  next  position  to  read  at. 

buf  [ 0...buf  len-1  ]  is  fiUed  with  the  characters  from  textsw 
beginning  at  index  pos,  and  is  nuU-terminated  only  if  there 
were  too  few  characters  to  fill  the  buffer. 

TEXTSW_CONTROL_CHARS_USE_FONT 

boolean 

If  FALSE,  control  characters  always  display  as  an 
up  arrow  followed  by  a  character,  instead  of  whatever 
glyph  is  in  the  current  font.  Default:  FALSE. 

TEXTSW_DI SABLE_CD 

boolean 

Stops  textsw  from  changing  current  working  directory 
(and  grays  out  the  associated  items  in  the  menu). 

Default:  FALSE. 
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Table  19-27  Text  Subwindow  Attributes —  Continued 


Attribute 


TEXTSW  DISABLE  LOAD 


Value  Type  Description 


boolean  Prevents  files  being  loaded  into  the  textsw  (and  grays  out 

the  associated  items  in  the  menu).  Default:  FALSE. 


TEXTSW  EDIT  COUNT 


Monotonically  inorementing  count  of  the  number  of  edits 
made  to  the  textsw.  Get. 


TEXTSW  FILE 


File  to  load.  Default:  NULL.  Create,  set. 


TEXTSW  FILE  CONTENTS 


initializes  the  text  subwindow  contents 

fi'om  a  fiile  yet  still  edits  the  contents  in  memory. 


TEXTSW  FIRST 


Zlero-based  index  of  first  displayed  characto'. 


TEXTSW  FIRST  LINE 


Zero-based  index  of  first  displayed  line. 


TEXTSW  HISTORY  LIMIT 


Number  of  user  action  sequences  that  can  be  undone. 
Default:  50.  Create,  get. 


TEXTSW  IGNORE  LIMIT 


Number  of  edits  textsw  allows  before  vetoing  destroy.  Valid  values 
are  0,  meaning  destroy  will  be  vetoed  if  any  edits  have  been  done,  and 
TEXTSW_INFINITY,  meaning  destroy  will  never  be  vetoed.  Default: 
0. 


TEXTSW  INSERT  FROM  FILE 


inserts  the  contents  of  a  file  into 
a  text  subwindow  at  the  current  insertion  point 


TEXTSW  INSERT  MAKES  VISIBLE 


Textsw_enum  Controls  whether  insertion  causes  repositioning  to  make 

inserted  text  visible.  Possible  values  are  TEXTSW_ALWAYS, 
TEXTSW_NEVER  and  TEXTSW_IF_AUTO_SCROLL. 
Default:  TEXTSW  IF  AUTO  SCROLL. 


TEXTSW  INSERTION  POINT 


Textsw_index  Index  of  the  current  insertion  point  Get  set 


TEXTSW  LEFT  MARGIN 


Number  of  pixels  in  the  margin  on  left  Default:  4.  Create,  get 


TEXTSW  LENGTH 


Length  of  the  textsw ’s  contents.  Get  only. 


TEXTSW  LINE  BREAK  ACTION 


Textsw_enum  Determines  how  the  textsw  treats  file  lines  too  big 
to  fit  on  one  display  line.  Possible  values  are  either 
TEXTSW_CLIP  or  TEXTSW_WRAP_AT_CHAR. 
Default:  TEXTSW  WRAP  AT  CHAR.  Create,  set 


TEXTSW  LOWER  CONTEXT 


Minimum  #  of  lines  to  maintain  between  insertion  point 
and  the  bottom  of  view.  Used  by  auto  scrolling  when  type-in 
would  disappear  off  bottom  of  view. 

-1  means  defeat  auto  scrolling.  Default;  2. 
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Table  19-27 

Text  Subwindow  Attributes —  Continued 

Attribute 

Value  Type 

Description 

TEXTSW_MEMORY_MAXIMUM 

int 

How  much  memory  to  use  when  not  editing  files.  This  attribute  only 
takes  effect  at  textsw  window  creation  time  or  after  the  window  has 
been  reset  via  textsw_j:eset().  The  lower  bound  of  the  attribute  is  1000 
bytes  which  is  silently  enforced.  Default:  20,000  bytes.  (If  a  great 
deal  of  text  will  be  inserted  into  die  text  subwindow,  either  by  the  pro¬ 
gram  or  the  user,  you  may  need  to  increase  this.) 

TEXTSW_MENU 

Menu 

The  text  subwindow’s  menu.  Get,  set. 

TEXTSW_MODIFIED 

boolean 

Whether  or  not  the  textsw  has  been  modified.  Get  only. 

TEXTSW_MULT I_CLI CK_SP ACE 

int 

Max  #  of  pixels  that  can  be  between  successive  mouse  clicks 
and  still  have  the  clicks  be  considered  a  multi-click.  Default:  3. 

TEXTSW_MOLT I_CLI CK_T I MEOUT 

int 

Max  #  of  milliseconds  that  can  be  between  successive 

mouse  clicks  and  still  have  the  clicks  be  considered 

a  multi-click.  Default:  390. 

TEXTSW_NOT IFY_PROC 

(procedure) 

Notify  procedure.  Form  is: 

void 

not  if  y_jproc  (textsw,  avlist) 

Textsw  textsw 

Attr  avlist  avlist 

Default:  NULL,  meaning  standard  procedure. 

TEXTSW_READ_ONLY 

boolean 

When  TRUE,  prevents  editing  of  the  displayed  text.  If  another  file 
is  loaded  in,  READ_ONLY  is  turned  off  again.  Default  FALSE. 

TEXTSW_SCROLLBAR 

Scrollbar 

Scrollbar  to  use  for  text  subwindow  scrolling. 

NULL  means  no  scrollbar. 

Default:  A  scrollbar  with  default  attributes. 

Note:  text  subwindow  has  a  scrollbar  by  default,  so  you  would 
only  use  this  to  get  no  scrollbar,  or  to  get  the  scroUbar  handle. 

TEXTSW_STATUS 

Textsw_status  * 

If  set,  specifies  the  address  of  a  variable  of  type 

Textsw  status  into  which  a  value  is  written  that  reflects 
what  happened  during  the  call  to  window_create(). 

(For  possible  values,  see  the  Textsw  status  Values  table). 

TEXTSW_STORE_CHANGES_FILE 

boolean 

If  TRUE,  Store  changes  the  file  being  edited  to  that  named 
as  the  target  of  the  Store.  If  FALSE,  Store  does  not  affect 
which  file  is  being  edited.  Default:  TRUE. 

TEXT  SW  ST  ORE_SELF_I S_S AVE 

boolean 

Causes  textsw  to  interpret  a  Store  to  the  name  of  the  current  file 
as  a  Save.  Default:  FALSE.  Create,  get. 
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Table  19-27 

Text  Subwindow  Attributes —  Continued 

Attribute 

Value  Type 

Description 

TEXTSW_UPDATE_SCROLLBAR 

(no  value) 

Causes  text  subwindow  to  update  the  bubble  in  the  scrollbar. 

Set  only  —  get  returns  NULL. 

TEXTSW__UPPER_CONTEXT 

int 

Min  #  of  lines  to  maintain  between  the  start  of  the  selection  and 
top  of  view.  -1  means  to  defeat  the  normal  actions.  Default:  2. 

Revision  A,  of  May  9,  1988 


370  SunView  1  Programmer’s  Guide 


Table  19-28  Textsw  aiCt.±oTi  Attributes 


Attribute 

Value  Type 

Description 

TEXT  S W_ACT 1 0N_CAP  S_LOCK 

boolean 

The  user  pressed  the  CAPS-lock  function  key  to  change  the 
setting  of  the  CAPS-lock  (it  is  initially  0,  meaning  off). 

TEXTSW  ACTION_CHANGED_DIRECTORy 

char  * 

The  current  working  directory  for  the  process  has  been 
changed  to  the  directory  named  by  the  provided  string  value. 

TEXTSW_ACT ION_ED I TED_F I LE 

char  * 

The  file  named  by  the  provided  string  value  has  been  edited. 
Appears  once  per  session  of  edits  (see  below). 

TEXTSW  ACTION_EDITED_MEMORY 

none 

moiutors  whether  an  empty  text  subwindow  has  bear  edited. 

TEXTSW  ACTION_FILE_IS_READONLY 

char  * 

The  file  named  by  the  provided  string  value  does  not  have 
write  permission. 

TEXTS W_ACT I ON_LOADED_F ILE 

char  * 

The  text  subwindow  is  being  used  to  view  the  file  named 
by  the  provided  string  value. 

TEXTSW_ACTION_TOOL_CLOSE 

(no  value) 

The  frame  containing  the  text  subwindow  should  become 
iconic. 

TEXTSW  ACTION_TOOL_DESTROY 

Event  * 

The  tool  containing  the  text  subwindow  should  exit, 
wifliout  checking  for  a  veto  from  other  subwindows. 

The  value  is  the  user  action  tiiat  caused  the  destroy. 

TEXTSW_ACTION_TOOL_QaiT 

Event  * 

The  tool  containing  the  text  subwindow  should  exit 
normally.  The  value  is  the  user  action  that  caused 
the  exit. 

TEXTSW  ACTION_TOOL_MGR 

Event  * 

The  tool  containing  the  text  subwindow  should  do  the 
window  manager  operation  associated  with  the 
provided  event  value. 

TEXTSW_ACTION_OSING_MEMORY 

(no  value) 

The  text  subwindow  is  being  used  to  edit  a  string  stored  in 
primary  memory,  not  a  file. 
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Table  19-29  Textsw 

status  Values 

"■.f"- . 

Value 

Description 

TEXTSW_STATUS_OKAY 

The  operation  encovmtered  no  problems. 

TEXTSW_STATOS_BAD_ATTR 

The  attribute  list  contained  an  illegal  or  unrecognized  attribute. 

TEXTSW_STATUS_BAD_ATTR_VALUE 

The  attribute  list  contained  an  illegal  value  for  an  attribute, 
usually  an  out  of  range  value  for  an  enumeration. 

TEXTSW_STATUS_CANNOT_ALLOCATE 

A  call  to  calloc(2)  or  malloc(2)  failed. 

TEXTSW_STATDS_CANNOT_OPEN_INPUT 

The  specified  input  file  does  not  exist  or  cannot  be  accessed. 

TEXTSW_STATUS_CANNOT_INSERT_FROM_FILE 

The  operation  encountered  a  problem  when  trying 
to  insert  firom  file. 

TEXTSW_STATUS_OUT_OF_MEMORY 

The  operation  ran  out  of  memory  while  editing  in  memory. 

TEXTSW_STATDS_OTHER_ERROR 

The  operation  encountered  a  problem  not  covered  by  any  of 
the  other  error  indications. 
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Definition 

Description 

Textsw_mark 

textsw_add_rnark  (textsw,  position,  flags) 

Textsw  textsw; 

Textsw_index  position; 
unsigned  flags; 

Adds  a  new  mark  at  position. 

flags  can  be  either  TEXTSW_MARK_DEFAULTS  or 

TEXTSW_MARK_MOVE_AT_INSERT. 

int 

textsw  append  file_naine  (textsw,  name) 

Textsw  textsw; 

char  *name; 

Returns  0  if  textsw  is  editing  a  file, 

and  if  so  appends  the  name  of  the  file  at  the  end  of  name. 

Textsw_index 

text sw_delete (textsw,  first,  last_plus_one) 

Textsw  textsw; 

Textsw_index  first,  last_plus_one; 

Returns  0  if  the  operation  fails. 

Removes  the  span  of  characters  beginning  with  first, 
and  ending  one  before  last_j>lus_one. 

Textsw_index  ^ 

textsw  edit (textsw,  unit,  count,  direction) 

Textsw  textsw; 

unsigned  unit,  count,  direction; 

Returns  0  if  the  operation  fails.  Erases  a  character,  word  or 
line,  depending  on  whether  unit  is  SELN_IiEVEL_FIRST, 
SELN  LEVEL_FIRST+1,  or  SELN_LEVEL_LINE.  If 
direction  is  0,  characters  after  the  ins^tion  point  are 
affected,  otherwise  characters  before  the  insCTtion  point  are 
affected.  The  operation  will  be  done  count  times. 

Textsw_index 

textsw  erase (textsw,  first,  last_plus_one) 

Textsw  textsw; 

Textsw  index  first,  last_jjlus_one; 

Returns  0  if  the  operation  fails. 

Equivalent  to  text  sw  delete  ( )  ,but  does  not 
affect  the  global  shelf. 

void 

textsw  file  lines_visible (textsw,  top,  bottom) 

Textsw  textsw; 

int  *top,  *bottom; 

Fills  in  top  and  bottom  with  the  file  line  indices  of 
the  first  and  last  file  lines  being  displayed  in  textsw. 

int 

textsw  find  bytes (textsw,  first,  last_plus_one, 
buf,  buf_len,  flags) 

Textsw  textsw; 

Textsw  index  *first,  *last^lus_one; 

char  *buf; 

unsigned  buf_len,  flags; 

Beginning  at  the  position  addressed  by  first,  searches  for  the 
pattern  specified  by  buf  of  length  buf_len.  Searches 
forwards  if  flags  is  0,  else  searches  backwards. 

Returns  —1  if  no  match,  else  matching  span  placed  in 
indices  addressed  by  first  and  last_plus_one. 
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Definition 

Description 

void 

textsw  remove_inark  (textsw,  mark) 

Textsw  textsw; 

Textsw_inark  mark; 

Removes  an  existing  mark  from  textsw. 

Textsw_index 

textsw  replace  bytes (textsw,  first, 

lastj>lus  one, 
buf,  buf_len) 

Textsw  textsw; 

Textsw_index  first; 
char  *buf; 

unsigned  buf  len; 

Replaces  the  character  span  from  first  to 
last  plus  one  by  the  characters  in  buf. 
last  plus  one.  The  return  value  is  the  net 
number  of  bytes  inserted.  The  number  is  negative  if  the 
original  string  is  longer  than  the  one  that  replaces  it.  If 
this  operation  fails,  it  wiU  return  a  value  of  0. 

void 

textsw_reset (textsw,  x,  y) 

Textsw  textsw; 

int  X,  y; 

Discards  edits  performed  on  the  contents  of  textsw. 

If  needed,  a  message  box  will  be  displayed  at  x,  y. 

unsigned 

textsw_save (textsw,  x,  y) 

Textsw  textsw; 

int  X,  y; 

Saves  any  edits  made  to  the  file  currently 
loaded  into  textsw.If  needed,  a  message  hox 
will  be  displayed  at  x,  y . 

int 

textsw  screen  line_count (textsw) 

Textsw  textsw; 

Returns  the  number  of  screen  lines  in  textsw. 

void 

textsw_scroll_lines (textsw,  count) 

Textsw  textsw; 

int  count ; 

Moves  the  text  up  or  down  by  count  lines.  If  count 
is  positive,  then  the  text  is  scrolled  up  on  the  screen, 

(forward  in  the  file);  if  negative,  the  text  is  scrolled  down, 
(backward  in  the  file). 

void 

textsw  set  selection  (textsw,  first,  last_jplus_one, 

type) 

Textsw  textsw; 

Textsw  index  first,  last  plus  one; 

unsigned  type; 

Sets  the  selection  to  begin  at  first  and  include  all 
characters  up  to  last_plus_one. 
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Definition 

Description 

unsigned 

t ext sw_s tore 

_file (textsw,  filename,  x,  y) 

Stores  the  contents  of  text  sw 

Textsw 

textsw; 

to  the  file  named  by  filename.  If  needed,  a 

char 

*filename; 

message  box  will  be  displayed  at  x,  y. 

int 

X,  y; 
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. . . 

. 

■ '  . 

. 

Attribute 

Type 

Description 

TTY_ARGV 

char  ** 

Argument  vector:  name  of  the  pro¬ 
gram  running  in  the  tty  subwindow, 
followed  by  arguments  for  that  pro¬ 
gram. 

TTY_CONSOLE 

boolean 

If  TRUE,  tty  subwindow  is  con¬ 
sole.  Set  only.  Default:  FALSE. 

TTY__PAGE__MODE 

boolean 

If  TRUE,  output  will  stop  after 
each  page.  Default:  FALSE. 

TTY_QUIT_ON_CHILD_DEATH 

boolean 

If  TRUE,  window  done  ()  is 
called  on  the  subwindow  when  its 
child  terminates.  Set  only.  Default: 

FALSE. 

Table  19-32  TTY  Subwindow  Functions 

Definition 

Description 

int 

ttysw_input (tty,  buf ,  len) 

Tty  tty; 

char  *buf; 

Appends  len  number  of  characters  from  buf 
onto  tty’s  input  queue.  It  returns  the  number 
of  characters  accepted. 

int  len; 

int 

ttysw_output (tty,  buf,  len) 

Tty  tty; 

char  *buf; 

int  len; 

Appends  len  number  of  characters  from  buf 
onto  tty’s  output  queue,  i.e.  they  are  sent 
through  the  terminal  emulator  to  the  TTY.  It 
returns  the  number  of  characters  accepted. 

Revision  A,  of  May  9, 1988 


Chapter  19  —  SunView  Interface  Summary  (777  Subwindow  Special  Escape  Sequences)  377 


Table  19-33 

TTY  Subwindow  Special  Escape  Sequences 

r . ‘  ‘  . - - . 

i.  . f  .  . . .  A'^'  .  .  .  .-.'i 

Escape  Sequence^^^ 

Description 

\E[lt 

open  frame. 

\E[2t 

close  frame. 

\E[3t 

move  frame  with  interactive  feedback. 

\E[3;T0P;LEFTt 

move  frame  to  location  specified  by  (TOP, LEFT). 

\E[4t 

resize  frame  with  interactive  feedback. 

\E [ 4 ; WIDTH; HEIGHTt 

resize  frame  to  WIDTH  and  HEIGHT. 

\E[5t 

expose. 

\E[6t 

hide. 

\E[7t 

redisplay. 

\E[8;R0WS;C0LSt 

resize  firame  so  its  width  and  height  are  ROWS  and  COLS. 

\E[llt 

report  if  frame  is  open  or  closed  by  sending  \  [  It  or  \  [2t,  respectively. 

\E[13t 

report  frame’s  position  by  sending  the  \K[3;TOP!LEFT  t  sequence. 

\E[14t 

report  frame’s  size  in  pixels  by  sending  fire  \E  [  3 ;  WIDTH;  HEIGHT  t  sequence. 

\E  [18t 

report  frame’s  size  in  characters  by  sending  the  \E  [  8  ; ROWS;  COLS  t  sequence. 

\E[20t 

report  the  frame  icon’s  label  by  sending  the  \E  [  'Llabel\E\  sequence. 

\E[21t 

report  frame’s  label  by  sending  the  \E]  \.label\E\  sequence. 

\E]lr£SCf\E\ 

set  frame’s  label  to  text. 

\E]Ij^/e\E\ 

set  frame’s  icon  to  the  icon  contained  in  file. 

\E]LZ^2he/\E\ 

set  icon’s  label  to  label. 

\E[>OPTl;  .  .  .OPTnh 

turn  requested  options  on.  The  only  currently  defined  option  is  1,  for  TTY__PAGE_MODE. 

\K[>OPTJ;  .  .OPTnk 

turn  requested  options  off. 
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Table  19-33  TTY  Subwindow  Special  Escape  Sequences —  Continued 


Escape  Sequence^^^ 

Description 

\E[>Gm;  .  .  .OPTnl 

report  current  option  settings  by  sending  \E  i>OPTxl  or  \E>OPTh.  for  each  option  j:. 

In  this  table  “\E”  denotes  the  <ESC>  character,  as  it  does  in  termcap. 
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Table  19-34 

Window  Attributes 

Attribute 

Value  Type 

Description 

WIN_BELOW 

Window 

Causes  the  window  to  be  laid  out  below  window  given  as  the  value. 

WIN_BOTTOM_MARGIN 

int 

Margin  at  bottom  of  window. 

WIN_CLIENT_DATA 

caddr_t 

Client’s  private  data  —  for  your  use. 

WIN_COLUMNS 

int 

Window’s  width  (including  left  and  right  margins)  in  columns. 

WI N_COLUMN_GAP 

int 

Gap  between  columns  in  the  window. 

WIN_COLUMN_WIDTH 

int 

Width  of  a  column  in  the  window. 

WIN_CONSUME_KBD_EVENT 

short 

Window  will  receive  this  event. 

WIN_CONSUME_KBD_EVENTS 

list  of  short 

Null  terminated  list  of  events  window  will  receive.  Create,  set. 

WIN_CONSUME_P ICK_EVENT 

short 

Window  will  receive  this  pick  event. 

WIN_CONSUME_P ICK_EVENTS 

list  of  short 

Null  terminated  list  of  pick  events  window  will  receive.  Create,  set. 

WIN_CDRSOR 

Cursor 

The  window’s  cursor.  Note:  the  pointer  returned  by 
window_get  ( )  points  to  per-process  static  storage. 

WI N_DEVI CE_NAME 

char  * 

UNIX  device  name  associated  with  window,  consisting  of  a  string  and 
numCTic  part,  e.g.  win  10.  Get  only. 

WI N_DEVI CE_NUMBER 

int 

Numeric  component  of  device  name.  Get  only. 

WIN_ERROR_MSG 

char  * 

Error  message  to  print  before  exit(l).  Create  only. 

WIN_EVENT_PROC 

(procedure) 

Client’s  callback  procedure  which  receives  input  events: 

Not i f y_value 

event_proc (window,  event,  arg) 

Window  window; 

Event  * event; 

caddr_t  arg; 

WI N_EVENT_ST ATE 

short 

Gets  the  state  of  the  specified  event  code.  For  buttons  and  keys, 
zero  means  “up,”  non-zero  means  “down.”  Get  only. 

WIN_FD  . 

int 

The  UNIX  file  descriptor  for  the  window.  Get  only. 

WIN_FIT_HEIGHT 

int 

Causes  window  to  fit  its  contents  in  the  height  dimension, 
leaving  a  margin  specified  by  the  value  given. 
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Table  19-34 

Window  Attributes- 

—  Continued 

Attribute 

Value  Type 

Description 

WIN_FIT_WIDTH 

int 

Causes  window  to  fit  its  contents  in  the  width  dimension, 
leaving  a  margin  specified  by  the  value  given. 

WIN_FONT 

Pixfont  * 

The  window’s  font.  Notes  for  the  current  release: 

tty  subwindows  don’t  use  WIN  FONT.  Frames  don’t  use  WIN  FONT 

to  render  their  labels;  however,  they  do  use  WIN  FONT 

in  calculating  WIN_COLUMNS  and  WIN_ROWS.  Setting  WIN_FONT 

does  not  cause  the  default  system  font  to  be  set. 

WIN_GRAB_ALL_INPUT 

boolean 

Window  will  get  all  events  regardless  of  location. 

WIN_HEIGHT 

int 

Window’s  height  in  pixels.  Value  of  WIN  EXTEND  TO  EDGE 
causes  subwindow  to  extend  to  bottom  edge  of  frame. 

Default:  WIN_EXTEND_TO_EDGE. 

WIN_HORI ZONTAL_SCROLLBAR 

Scrollbar 

Horizontal  scrollbar. 

WI N_I GNORE_KBD_EVENT 

short 

Window  will  not  receive  this  event. 

WIN_IGNORE_KBD_EVENTS 

list  of  short 

Null  terminated  list  of  events  window  will  not  receive.  Create,  set. 

WI  N_I  GNORE_P  I  CK_E  VENT 

short 

Window  wUl  not  receive  this  pick  event. 

WIN_I GNORE_P I CK_EVENTS 

list  of  short 

Null  terminated  list  of  pick  events  window  will  not  receive.  Create,  set. 

WIN_INPUT_DESIGNEE 

int 

Window  which  gets  events  this  window  doesn’t  consume.  (Note  that 
the  value  must  be  the  WIN_DEVICE_NUMBER  of  the  designee). 

WIN__KBD_FOCUS 

boolean 

Whether  or  not  the  window  has  the  keyboard  focus. 

WIN_KBD_INPUT_MASK 

Inputmask  * 

Window’s  keyboard  inputmask.  Note:  the  pointer  returned  by 
window  get  ( )  points  to  per-process  static  storage. 

WIN_LEFT_MARGIN 

int 

Margin  at  left  of  window. 

WIN_MENU 

Menu 

Window’s  menu.  Note:  In  the  current  release  this  doesn’t  work  for 
panels  or  tty  subwmdows. 

WIN_MOUSE_XY 

int,  int 

Mouse’s  position  within  the  window.  Set  only. 

WIN_NAME 

char  * 

Name  of  window  (currently  unused  by  SunView). 

WIN_OWNER 

Window 

Owner  of  window.  Get  only. 

WIN_PERCENT_HEIGHT 

int 

Sets  a  subwindow’s  height  as  a  percCTitage  of  the  frame’s  height. 
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Table  19-34 

Window  Attributes- 

—  Continued 

Attribute 

Value  Type 

Description 

WIN_PERCENT_WIDTH 

int 

Sets  a  subwindow’s  width  as  a  percentage  of  the  frame’s  width. 

WIN_PICK_I1SIP0T_MASK 

Inputmask  * 

Window’s  pick  inputmask.  Note:  the  pointer  returned  by 
window  get  { )  points  to  per-process  static  storage. 

WIN_PIXWIN 

Pixwin  * 

The  window’s  pixwin.  Get  only. 

WIN_RECT 

Rect* 

Rect  of  the  window.  For  frames,  same  as  FRAME  OPEN  RECT. 

Note:  the  pointer  returned  by  window  get  ( )  for  this  attribute 
points  to  per-process  static  storage. 

WI N_RI GHT_MARGIN 

int 

Margin  at  right  of  window. 

WIN_RIGHT_OF 

Window 

Causes  the  window  to  be  laid  out  just  to  the 
right  of  the  window  given  as  the  value. 

WIN_ROW_GAP 

int 

Gap  between  rows  in  the  window. 

WIN_ROW_HEIGHT 

int 

Height  of  a  row  in  the  window. 

WIN_ROWS 

int 

Window’s  height  (including  top  and  bottom  margins)  in  rows. 

WIN_SCREEN_RECT 

Rect* 

Rect  of  the  screen  containing  the  window.  Get  only. 

Note:  the  pointer  returned  by  window_get  ( >  for  this  attribute 
points  to  per-process  static  storage. 

WIN_SHOW 

boolean 

Causes  the  window  to  be  displayed  or  undisplayed. 

WIN_TOP_MARGIN 

int 

Margin  at  top  of  window. 

WIN_TYPE 

Window_type 

Type  of  window.  One  of  FRAME_TYPE,  PANEL_TYPE, 

CANVAS_TYPE,  TEXTSW_TYPE  or  TTY_TYPE.  Get  only. 

WIN_VERT  I  CAL__SCROLLBAR 

Scrollbar 

Vertical  scrollbar. 

WIN_WIDTH 

int 

Window’s  width  in  pixels.  Value  of  WIN  EXTEND  TO  EDGE 
causes  subwindow  to  extend  to  right  edge  of  frame. 

Default:  WIN_EXTEND_TO_EDGE. 

WIN_X 

int 

X  position  of  window,  relative  to  owner. 

WIN_Y 

int 

y  position  of  window,  relative  to  owner. 
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Table  19-35 

Frame  Attributes 

. . . 

Attribute 

Value  Type 

Description 

FRAME_ARGS 

int,  char  ** 

Interpret  command  line  arguments.  Strips  -W  command-line  frame 
arguments  out  of  argv.  Create  only. 

FRAME_ARGC_PTR_ARGV 

int  *,  char  ** 

Interpret  command  line  args.  Strips  -W  command-line  frame  argu¬ 
ments  out  of  argv,  and  decremoits  argc  accordingly.  Create  only. 

FRAME_BACKGROUND_COLOR 

struct  singlecolor  * 

Background  color. 

FRAME_CLOSED 

boolean 

Whether  frame  is  currently  closed. 

FRAME_CLOSED_RECT 

Rect* 

Frame’s  rect  when  closed. 

FRAME_CMDLINE_HELP_PROC 

(procedure) 

Called  when  usct  types  the  command-line  argument  -WH.  Default: 
frame  cmdline  help (program_name) 
char  *program_name; 

FRAME_CURRENT__RECT 

Rect  * 

Returns  either  FRAME_OPEN_RECT  or  FRAME_CLOSED_RECT, 
depending  on  the  value  of  FRAME  CLOSED. 

Note:  in  the  current  release,  there  is  a  bug  in  the  behavior 
of  FRAME  CURRENT  RECT  for  subframes.  It  is  set  relative 
to  the  owner  frame,  but  it  is  retrieved  relative  to  the  screen. 

FRAME_DEFAULT_DONE_PROC 

(procedure) 

Default  value  of  FRAME_DONE_PROC.  Get  only. 

The  default  procedure  is  to  set  the  subframe  to  WIN_SHOW,  FALSE. 

FRAME_DONE_PROC 

(procedure) 

Client’s  proc  called  when  user  chooses  ‘Done’  from  subframe’s  menu: 
done_j3roc  (frame) 

Frame  frame; 

FRAME_EMBOLDEN_LABEL 

boolean 

If  TRUE,  frame’s  label  is  rendered  in  bold. 

FRAME_FOREGROUND_COLOR 

struct  singlecolor  * 

Foreground  color. 

FRAME_ICON 

Icon 

The  frame’s  icon. 

FRAME_INHERI T_COLORS 

boolean 

If  TRUE,  colormap  of  frame  is  inherited  by  subwindows. 

FRAME_LABEL 

char  * 

The  frame’s  label. 

FRAME_NO_CONFIRM 

boolean 

Set  to  TRUE  before  destroying  a  frame 
to  defeat  confirmation.  Set  only. 

FRAME_NTH_SUBFRAME 

int 

Returns  frame’s  nth  (from  0)  subframe.  Get  only. 
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Table  19-35 

Frame  Attributes— 

-  Continued 

Attribute 

Value  Type 

Description 

FRAME_NTH_SOBWI NDOW 

int 

Returns  frame’s  nth  (from  0)  subwindow.  Get  only. 

FRAME_NTH_WINDOW 

int 

Returns  frame’s  nth  (from  0)  window,  regardless  of  whether 
the  window  is  a  frame  or  a  subwindow.  Get  only. 

FRAME_OPEN_RECT 

Rect  * 

Frame’s  rect  when  open. 

FRAME_SHOW_LABEL 

boolean 

Whether  the  label  is  shown.  Default: 

TRUE  for  base  frames,  FALSE  for  subframes. 

FRAME_SUBWINDOWS_ADJUSTABLE 

boolean 

User  can  move  subwindow  boundaries.  Default:  TRUE. 
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Table  19-36  Window  Functions  and  Macros 


.  ^  ^  ^  ^  ^  ^  ^  ■* 

Definition 

Description 

void 

window_bell (win) 

Window  win; 

Queries  the  user  defaults  database 
to  see  if  the  user  wants  the  bell  to  be 
sounded,  the  window  to  be  flashed,  or  both. 

Window 

window_create (owner,  type,  attributes) 

Window  owner; 

<window  type>  type; 

<attribute-list>  att  ribu t e  s ; 

Creates  a  window  and  returns  its  handle, 
type  is  one  of  FRAME,  PANEL 

TEXTSW,  TTY,  or  CANVAS. 

void 

window  default  event^p roc (window,  event,  arg) 
Window  window; 

Event  *  event ; 

caddr_t  arg; 

Calls  the  default  event  procedure. 

The  arguments  passed  in  are  the  window  (canvas  or  panel), 
the  event,  and  an  optional  argument  pertaining  to  the  event. 

window  destroy (win) 

Window  win; 

Destroys  win,  and  any  subwindows  or 
subframes  owned  by  win. 

window  done (win) 

Window  win; 

Destroys  the  entire  hierarchy  to  which  win  belongs. 

window_fit (win) 

Window  win; 

Causes  win  to  fit  its  contents 

in  both  dimensions,  A  macro,  defined  as; 

window  set (win,  WIN_FIT,  0,  0). 

window  f it_height (win) 

Window  win; 

Causes  win  to  fit  its  contents 

in  the  vertical  dimension.  A  macro,  defined  as: 
window  set (win,  WIN_FIT_HEIGHT,  0,  0), 

window_fit_width (win) 

Window  win; 

Causes  win  to  fit  its  contents 

in  the  horizontal  dimension.  A  macro,  defined  as: 
window  set (win,  WIN_FIT_WIDTH,  0,  0). 

caddr_t 

window  get (win,  attribute) 

Window  win; 

Window  attribute  attribute; 

Retrieves  the  value  of  an  attribute  for  win. 
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Table  19-36  Window  Functions  and  Macros —  Continued 


Definition 

Description 

caddr  t 

window  loop (subframe) 

Frame  subframe; 

Causes  subframe  to  be  displayed,  and  receive  all 
input.  The  call  will  not  return  imtil  window  return  ( ) 
is  called  from  one  of  the  application’s  notify  procs. 

void 

window_main_loop (base_frame) 

Frame  base_frame; 

Displays  base_f  rame  on  the  screen  and  begins  the 
processing  of  events  by  passing  control  to  the  Notifier. 

int 

window  read  event (window,  event) 

Window  window; 

Event  *event; 

Reads  the  next  input  event  for  window. 

In  case  of  error,  sets  the  global  variable  errno 

and  returns  -1. 

void 

window  refuse_kbd_focus (window) 

Window  window; 

When  your  event  handler  receives  a  KBD_REQUEST 
evait,  call  this  function  if  you  do  not  want  your 
window  to  become  the  keyboard  focus. 

void 

window  release  event  lock (window) 

Window  window; 

Releases  the  event  lock,  allowing  other  processes  to  receive  input. 

void 

window  return (value) 
caddr_t  value; 

Usually  called  from  one  of  the  application’s  panel  item 
notify  procs.  Causes  window_loop  ()  to  return. 

window  set  (win,  attributes) 

Window  win; 

<attribute-list>  attributes; 

Sets  the  value  of  one  or  more  of  win’s  attributes. 

attributes  is  a  null-terminated  attribute  list 
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Table  19-37 


Command  Line  Frame  Arguments 


Flag 

Long  Flag 

Arguments 

Corresponding  Attributes 

-Wb 

-background  color 

red  green  blue 

FRAME_BACKGROUND_COLOR 

-Wh 

-height 

lines 

WIN_ROWS 

-WH 

-help 

— 

(Causes  FRAME_CMDLINE_HELP_PROC  to  be  called.) 

-Wf 

-foreground  color 

red  green  blue 

FRAME_FOREGROUND_COLOR 

-Wg 

- set_def ault_color 

— 

FRAME_INHERI T_COLORS ,  TRUE 

-Wi 

-iconic 

— 

FRAME_CLOSED ,  TRUE 

-WI 

-icon_image 

filename 

ICON_IMAGE  of  frame’s  icon^®^ 

-WI 

-label 

label 

FRAME_LABEL 

-WL 

-icon_lab6l 

label 

ICON_LABEL  of  frame’s  icon 

-Wn 

-no_label 

— 

FRAME_SHOW_LABEL,  FALSE 

-Wp 

-position 

xy 

WIN_X,  WIN_Y 

-WP 

-icon_position 

xy 

FRAME_CLOSED_RECT 

-Ws 

-size 

xy 

WIN_WIDTH,  WIN_HEIGHT 

-Wt 

-font 

filename 

(Sets  system  default  font) 

-WT 

-icon_font 

filename 

ICON_FONT  of  frame’s  icon 

-Ww 

-width 

columns 

WIN  COLUMNS 

The  -WI  option  will  not  work  if  the  application’s  code  does  not  already  specify  its  icon. 
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Example  Programs 


Example  Programs  .  389 

Source  Available .  389 

AA.  filer . 389 

A.2.  image _browser_l  .  401 

A.3.  image _browser_2 .  406 

A.4,  tty_io .  412 

A.5.  font_menu  .  416 

A.6.  resize_demo .  425 

A.7.  detool .  430 

A.8.  typein .  437 

A.9.  Programs  that  Manipulate  Color . 441 

color  edit .  44 1 

animatecolor .  447 

A.  10.  Two  gfx  subwindow-based  programs  converted  to  use 

SunView .  454 

bounce  .  454 

spheres .  461 


Source  Available 


A.l.  filer 


Example  Programs 


If  the  appropriate  optional  software  category  has  been  installed  or  mounted  on 
your  system,  the  source  code  for  some  of  these  examples  programs  is  available 
on-line  in  /usr/ share/ src/ sun/ suntool/examples.  In  addition,  the 
directory  above  this  (/usr/share/ src/ sun/ suntool)  contains  the  source 
for  many  of  the  SunView  1  programs  in  the  SunOS,  such  as  text  edit, 
perfmeter,  and  iconedit. 


This  program  is  discussed  in  Chapter  4,  Using  Windows.  It  displays  a  listing  in  a 
tty  subwindow,  which  the  user  manipulates  through  pand  items. 

If  the  user  presses  the  [  Props  i  key  in  the  panel,  or  chooses  ‘Props’  from  the  frame 
menu,  or  pushes  the  Set  Is  flags  button,  a  pop-up  subframe  appears,  filer  uses  the 
Selection  Service  to  determine  what  file  name  the  user  has  selected,  and  creates  a 
pop-up  text  subwindow  where  that  file  is  displayed. 

filer  uses  the  alerts  package  to  ask  the  user  for  confirmation  and  put  up  messages. 
It  also  includes  old  code  which  mimics  alerts  by  using  window_loop  ( )  to  put 
up  a  subframe,  but  programs  written  for  SunOS  Release  4.0  and  beyond  in  gen¬ 
eral  will  have  no  need  for  this. 
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/*  4.0  filer. c  */ 

/*****************************************************************************/ 

#include  <suntool/sunview.h> 

#include  <suntool/panel .h> 

#include  <suntool/tty .h> 
tinclude  <suntool/textsw. h> 

#include  <suntool/seln .h> 
linclude  <suntool/alert .h> 

#include  <sys/stat..h>  /*  stat  call  needed  to  verify  existence  of  files  */ 


/*  these  objects 

Frame 

Panel 

Tty 

Textsw 

Panel_item 

int 


are  global  so  their  attributes  can  be  modified  or  retrieved  */ 
base_frame,  edit_frame,  ls_flags_f rame; 
panel,  ls_f lags_panel; 
ttysw; 
editsw; 

dir_item,  fname_item,  filing_mode_item,  done_item; 
quit_conf  irmed_f  rom_j>anel  ; 


#define  MAX_FILENAME_LEN  256 

#define  MAX  PATH  LEN  1024 


char  *getwd(); 

main(argc,  argv) 
int  argc; 
char  **argv; 

{ 

static  Notify_value  f iler_destroy_func {} ; 
void  ls_flags_proc  0  ; 

base_frame  =  window_c reate (NULL,  FRAME, 

FRAME_ARGS,  argc,  argv, 

FRAME_LABEL,  "filer”, 

FRAME_PROPS_ACTION_PROC,  1 s_f lags_proc , 
FRAME_PROPS_ACTIVE,  TRUE, 

FRAME_NO_CONFIRM,  TRUE, 

0); 

(void)  notify_interpose_destroy_func  (base_frame,  filer_destroy_func) ; 


create_panel_subwindow () ; 
create_tty_subwindow ()  ; 
create_edit_popup () ; 
create_ls_f  lags_popup  ()  ; 
quit_conf irmed_f rom_panel  =  0; 


window_main_loop (base_frame)  ; 
exit (0) ; 

} 

create_tty_subwindow 0 

{ 

ttysw  =  window_create (base_frame,  TTY,  0)  ; 

} 


create_edit__popup  ( ) 
( 
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edit_frame  =  window_create (base_frame,  FRAME, 
FRAME_SHOW_LABEL,  TRUE, 

0); 

editsw  =  window_create (edit_f rame,  TEXTSW,  0); 

} 

create_panel_subwindow ( ) 

{ 

void  ls__proc(),  ls_flags_proc  () ,  quit_proc  ()  ,  edit_proc(), 
edit_sel_proc () ,  del_proc () ; 

char  current_dir [MAX_PATH_LEN] ; 

panel  =  window_create (base_frame,  PANEL,  0); 


(void)  panel_create_item (panel, 
PANEL_LABEL_X, 

PANEL_LABEL_Y , 
PANEL_LABEL_IMAGE , 
PANEL_NOTIFy_PROC , 

0); 

(void)  panel_create_item (panel, 
PANEL_LABEL_IMAGE , 
PANEL_NOTIFY_PROC , 

0); 

(void)  panel_create_item (panel , 
PANEL_LABEL_IMAGE , 
PANEL_NOTIFY_PROC , 

0); 

(void)  panel_create_item (panel, 
PANEL_LABEL_IMAGE , 
PANEL_NOTIFY_PROC , 

0)  ; 


PANEL_B0TT0N, 

ATTR_C0L (0)  , 

ATTR_ROW(0)  , 

panel_button_image (panel, 
ls_proc, 

PANEL_BUTTON, 

panel_button_image (panel, 
ls_flags^roc, 

PANEL_BUTTON, 

panel_button_image (panel , 
edit_proc, 

PANEL_BUTTON, 

panel_button_image (panel, 
del_proc. 


(void)  panel_create_item (panel,  PANEL_BUTTON , 

PANEL_LABEL_IMAGE,  panel_button_image (panel, 

PANEL_NOTIFY_PROC,  quit_proc, 

0); 


filing  mode  item  =  panel  create__item (panel,  PANEL_CYCLE, 


PANEL_LABEL_X, 
PANEL_LABEL_Y, 
PANEL_LABEL_STRING, 
PANEL_CHOICE_STRINGS , 

0); 

(void)  panel_create_item (panel 
PANEL_LABEL_X, 
PANEL_LABEL_Y, 

0); 


ATTR_COL(0) , 

ATTR_R0W(1), 

"Filing  Mode : " , 

"Use  \"File:\"  item", 
"Use  Current  Selection", 


PANEL_MESSAGE, 

ATTR_COL (0)  , 
ATTR  ROW (2)  , 


dir  item  =  panel_create_item (panel , 
~PANEL_LABEL_X , 

PANEL  LABEL  Y, 


PANEL_TEXT, 
ATTR_COL (0)  , 
ATTR  ROW  (3) , 
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"List  Directory",  0,  0)  , 


"Set  Is  flags",  0,  0) , 


"Edit",  0,  0), 


"Delete",  0,  0)  , 


"Quit",  0,  0), 
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P ANEL_yALUE_D I SPLAY_LENGTH , 

PANEL_VALUE, 

PANEL_LABEL_STRING, 

0); 


60, 

getwd (current_dir) , 
"Directory;  ", 


fname_item  =  panel_create_itein  (panel 
PANEL_LABEL_X, 

PANEL_LABEL_Y, 

PANEL_LABEL_DISPLAY_LENGTH, 

PANEL_LABEL_STRING, 

0); 


,  PANEL_TEXT 
ATTR_COL (0) , 
ATTR_ROW(4)  , 
60, 

"File:  ", 


window_f it_height (panel) ; 

window_set  (panel,  PANEL_CARET_ITEM,  fnanie_item,  0) ; 


create_ls_flags  jjopup  0 

{ 

void  done_proc(); 

ls_flags_frame  =  window_create (base_frame,  FRAME,  0) ; 


ls_flags_panel  =  window_create (ls_flags_f rame,  PANEL,  0) ; 


panel_create_item (ls_f lags_panel , 
PANEL_ITEM_X, 
PANEL_ITEM_Y, 

P ANEL_LABEL_STRING , 
PANEL_CLIENT_DATA , 

0); 


PANEL_MESSAGE, 

ATTR_C0L(14)  , 

ATTR_R0W (0) , 

"Options  for  Is  convmand", 

11  If 


panel_create_item  (1 s_f  lags_panel , 
PANEL_ITEM_X, 
PANEL_ITEM_Y, 

PANEL_D I SPLAY_LEVEL , 
PANEL_LABEL__STRING, 
PANEL_CHOICE_STRINGS , 
PANEL_CLIENT_DATA, 

0); 

panel_create_item(ls_flags_panel, 

PANEL_ITEM_X, 

PANEL_ITEM_Y, 

PANEL_D I SPLAY_LEVEL , 
PANEL_LABEL_STRING, 
PANEL_CHOICE_STRINGS , 
PANEL_CLIENT_DATA , 

0); 


PANEL_CYCLE, 
ATTR_COL(0)  , 
ATTR_R0W(1)  , 
PANEL_CDRRENT, 
"Format ; 

"Short",  "Long",  0, 
"  1  ", 


PANEL_CYCLE, 

ATTR_C0L (0) , 

ATTR_ROW (2) , 

PANEL_CURRENT, 

"Sort  Order; 

"Descending",  "Ascending",  0, 
"  r  ", 


panel_creat  e_i  t  em  ( 1  s_f  lags_panel , 
PANEL_ITEM_X, 
PANEL_ITEM_Y, 

PANEL_D I SPLAY_LEVEL , 
PANEL_LABEL_STRING, 
PANEL_CHOICE_STRINGS , 

PANEL_CLIENT_DATA, 

0); 


PANEL_CYCLE, 

ATTR_C0L (0)  , 

ATTR_R0W(3} , 

PANEL_CURRENT, 

"Sort  criterion: 

"Name",  "Modification  Time", 
"Access  Time",  0, 

"  tu” , 
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panel_create_item(ls_flags_panel,  PANEL_CYCLE, 


PANEL_ITEM_X, 

PANEL_ITEM_Y, 

PANEL_D I SPLAY_LEVEL , 
PANEL_LABEL_STRING, 
PANEL_CHOICE_STRINGS , 
PANEL_CLI ENT_DATA , 

0); 


ATTR_COL(0) , 

ATTR_R0W(4)  , 

PANEL_CURRENT, 

"For  directories,  list: 
"Contents",  "Name  Only",  0, 
"  d  ", 


panel_create_item (ls_f lags_panel ,  PANEL_CYCLE, 


PANEL_ITEM_X, 

PANEL_ITEM_Y, 

PANEL_D I SPLAY_LEVEL , 
PANEL_LABEL_STRING, 
PANEL_CHOICE_STRINGS , 
PANEL_CLI ENT_DATA , 

0); 


ATTR_COL(0) , 

ATTRJR0W(5> , 

PANEL_CURRENT, 

"Recursively  list  subdirectories?  ", 
"No",  "Yes",  0, 

"  R  ", 


panel_create_item  (1 s_f lags_panel ,  PANEL_CYCLE , 


PANEL_ITEM_X, 

PANEL_ITEM_Y, 

P ANEL_D I SP LAY_LEVEL , 
PANEL_LABEL_STRING, 
PANEL_CHOICE_STRINGS , 
PANEL_CLIENT_D ATA , 

0); 


ATTR_COL(0) , 
ATTR_ROW(6) , 
PANEL_CURRENT, 
"List  ' . '  files? 
"No",  "Yes",  0, 


panel_create_item  (ls_f lags_panel ,  PANEL_CYCLE, 

P ANEL_I TEM_X ,  ATTR_COL ( 0 ) , 

P ANEL_I TEM_Y ,  ATTR_R0W ( 6 ) , 

PANEL_DISPLAY_LEVEL,  P  ANEL__CURRENT , 

PANEL_LABEL_STRING,  "Indicate  type  of  file?  ", 

PANEL_CHOICE_STRINGS,  "No",  "Yes",  0, 

PANEL_CLIENT_DATA,  "  F  ", 

0); 

done_item  =  panel_create_item  (ls_f lags_panel,  PANEL_BUTTON, 

PANEL_I TEM_X ,  ATTR_C0L ( 0 } , 

PANEL_I TEM_Y ,  ATTR_ROW ( 7 } , 

PANEL_LABEL_IMAGE,  panel_button_iinage  {panel,  "Dorie",  0,  0)  , 

PANEL_NOTIFY_PROC,  done_j)roc, 

0); 

window_fit (ls_flags_panel) ;  /*  fit  panel  around  its  items  */ 
window  fit (Is  flags  frame) ;  /*  fit  frame  around  its  panel  */ 


char  * 

compose_ls_options () 

{ 

static  char  flags [20]; 


char 

char 

int 

Panel_item 

char 

int 


*ptr; 

flag; 

first_flag  =  TRUE; 
item; 

*  cl ient_dat  a ; 
index; 


ptr  =  flags; 
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holder  =  seln_inquire (SELN_PRIMARY) ; 

buffer  =  seln_ask (Sholder,  SELN_REQ_CONTENTS_ASCII,  0,  0); 
strncpy ( 

filename,  buffer->data  +  sizeof (Seln_attribute) ,  MAX_FILENAME_LEN) ; 
return (filename) ; 

} 

/*  return  1  if  file  exists,  else  print  error  message  and  return  0  */ 
stat_file (filename) 
char  *filename; 

{ 

static  char  previous_dir  [MAX_PATH_IiEN]  ; 
char  *current_dir; 
char  this_file [MAX_PATH_LEN] ; 
struct  stat  statbuf; 

current_dir  =  (char  * ) panel_get_value (dir_item) ; 

if  (strcmp (current_dir,  previous_dir) )  { 

chdir ( (char  * ) panel_get_value (dir_item) ) ; 
strcpy (previous_dir,  current_dir) ; 

} 

sprintf (this_file,  "%s/%s",  current_dir,  filename); 
if  (stat (this_file,  Sstatbuf)  <  0)  { 

char  buf [MAX_FILENAME_LEN+11] ;  /*  big  enough  for  message  */ 

sprintf  (buf,  *'%s  not  found.”,  this_file)  ; 
msg(buf,  1); 
return  0 ; 

} 

return  1 ; 

} 

void 

edit_proc  0 

{ 

void  edit_file_j>roc  ()  ,  edit_sel_proc  ()  ; 

int  file_mode  =  (int) panel_get_value (filing_mode_item) ; 

if  (file_mode)  { 

(void)  edit_sel_proc  0  ; 

}  else  { 

(void)  edit_f  ile_proc  ()  ; 

} 

} 

void 

edit_f  ile_j)roc  () 

{ 

char  *filename; 

/*  return  if  no  selection  */ 

if  (! St rlen (filename  =  (char  *) panel_get_value (fname_item) ) )  { 

msgC'Please  enter  a  value  for  \"File:\".”,  1); 
return; 

} 

/*  return  if  file  not  found  */ 
if  ( ! stat_f ile (filename) ) 
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return; 


window_set (editsw,  TEXTSW_FILE,  filename,  0); 

window_set {edit_frame,  FRAME_LABEL,  filename,  WIN_SHOW,  TRUE,  0) ; 


edit_sel_proc ( ) 

{ 

char  *filename; 

/*  return  if  no  selection  */ 
if  (! strlen (filename  =  get_selection  () ) )  { 
msg( "Please  select  a  file  to  edit.",  0); 
return; 

} 

/*  return  if  file  not  found  */ 
if  ( ! stat_file (filename) ) 
return; 

window  set (editsw,  TEXTSW  FILE,  filename,  0) ; 


window  set (edit  frame,  FRAME  LABEL,  filename,  WIN  SHOW,  TRUE,  0) ; 


void 

del  proc  () 


char  buf[300]; 

char  * filename; 
int  result; 

Event  event;  /*  unused  */ 

int  file_mode  =  (int ) panel_get_value (f iling_mode_item) ; 

/*  return  if  no  selection  */ 
if  (file_mode)  { 

if  (! strlen (filename  =  get_selection () ) )  { 

msgC'Please  select  a  file  to  delete.",  1); 
return; 

} 

}  else  { 

if  (! strlen (filename  =  (char  *)panel_get_value (fname_item) ) )  { 

msgC'Please  enter  a  file  name  to  delete.",  1); 
return; 

} 

} 

/*  return  if  file  not  found  */ 
if  ( ! stat_f ile (filename) ) 

return; 

/*  user  must  confirm  the  delete  */ 
result  =  alert_prompt  (base'_frame,  Sevent, 

ALERT_MESSAGE_STRINGS , 

"Ok  to  delete  file:", 
filename. 
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0' 

ALERT_BUTTON_YES,  "Confirm,  delete  file", 

ALERT_BUTTON_,NO,  "  Cancel " , 

0)  ; 

switch  (result)  { 
case  ALERT_yES: 

unlink (filename) ; 

sprintf(buf,  "%s  deleted.",  filename); 

msg{buf,  0); 

break; 

case  ALERT_NO: 
break; 

case  ALERT_FAILED :  /*  not  likely  to  happen  unless  out  of  FDs  */ 
sprintf (buf ,  "Ok  to  delete  file  %s?",  filename); 
result  =  conf irm_yes (buf) ; 
if  (result)  { 

unlink (filename) ; 

sprintf (buf,  "%s  deleted.",  filename); 
msg(buf,  1); 

} 

break; 

} 

} 

int 

confirm_quit  () 

{ 

int  result; 

Event  event;  /*  unused  */ 

char  *msg  =  "Are  you  sure  you  want  to  Quit?"; 

result  =  alert_prompt (base_frame,  Sevent, 

ALERT_MESSAGE_STRINGS , 

"Are  you  sure  you  want  to  Quit?", 

0, 

ALERT_BUTTON_YES ,  " Confirm" , 

ALERT_BUTT0N_N0 ,  "Cancel " , 

0)  ; 

switch  (result)  { 
case  ALERT_YES: 
break; 

case  ALERT_NO: 
return  0 ; 

case  ALERT_FAILED :  /*  not  likely  to  happen  unless  out  of  FDs  */ 
result  =  conf irm_yes (msg)  ; 
if  (! result)  { 
return  0; 

} 

break; 

} 

return  1; 

} 

static  Notify_value 
filer_destroy_func (client,  status) 

Notify_client  client; 

Destroy_status  status; 

{ 
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if  (status  ==  DESTROY_CHECKING)  { 

if  (quit_confirmed_f rom_panel)  { 

return (notify_next_destroy_func (client,  status) ) ; 

}  else  if  (confirm_quit 0  ==  0)  { 

(void)  notify_veto_destroy ( (Notify_client ) (LINT_CAST (client) ) ) ; 
return (NOTIFY  DONE) ; 


return (notify_next_destroy_func (client,  status) ) ; 


void 

quit_proc  0 


if  (confirm_quit  ()  )  { 

quit_confirmed_f rom_panel  -  1; 
window  destroy (base  frame); 


msg (msg,  beep) 
char  *msg; 
int  beep; 

{ 

char  buf[300]; 

int  result; 

Event  event;  /*  unused  */ 

char  *contine_msg  =  "Press  \"Continue\"  to  proceed."; 

result  =  alert_prompt  (base_frame,  &event, 

ALERT_MESS AGE_STRINGS , 
msg, 

contine_msg, 

0, 

ALERT_NO_BEEPING,  (beep)  ?  0:1, 

ALERT_BaTTON_YES,  "Continue", 

ALERT_TRIGGER,  ACTI0N_ST0P,  /*  allow  either  YES  or  NO  answer  */ 

0); 

switch  (result)  { 
case  ALERT_YES; 

case  ALERT_TRIGGERED :  /*  result  of  ACTI0N_ST0P  trigger  */ 
break ; 

case  ALERT_FAILED :  /*  not  likely  to  happen  unless  out  of  FDs  */ 
sprint f (buf,  "%s  Press  \"Continue\"  to  proceed.",  msg); 
result  =  conf irm_ok (buf) ; 
break; 


/*  confirmer  routines  to  be  used  if  alert  fails  for  any  reason  */ 

static  Frame  init_conf irmer () ; 

static  int  confirmO; 

static  void  yes  no_ok () ; 


confirm_yes (message) 

char  *message; 
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return  confirm (message,  FALSE); 


int 

confirm_ok (message) 

char  *message; 

{ 

return  confirm (message,  TRUE); 


static  int 

confirm (message,  ok_only) 
char  *message; 

int  ok_only; 


Frame 

int 


confirmer; 

answer; 


/*  create  the  confirmer  */ 

confirmer  =  init_confirmer (message,  ok_only) ; 

/*  make  the  user  answer  */ 

answer  =  (int)  window_loop (confirmer) ; 

/*  destroy  the  confirmer  */ 

window_set (confirmer,  FRAME_NO_CONFIRM,  TRUE,  0) ; 
window_destroy (confirmer) ; 
return  answer; 


static  Frame 

init_confirmer (message,  ok_only) 
char  *message; 

int  ok_only; 


Frame 

Panel 

Panel  item 


confirmer; 
panel ; 

mes  sage_it em; 

left,  top,  width,  height; 


struct  pixrect  *pr; 

confirmer  =  window_create (0,  FRAME,  FRAME_SHOW_LABEL,  FALSE,  0) ; 
panel  =  window_create (confirmer,  PANEL,  0); 

message_item  =  panel_create_item (panel,  PANEL_MESSAGE, 

PANEL_LABEL_STRING,  message,  0) ; 

if  (ok_only)  ( 

pr  =  panel_button_image (panel,  "Continue",  8,  0); 
width  =  pr->pr_width; 

}  else  { 

pr  =  panel_button_image (panel,  "Cancel",  8,  0); 
width  =  2  *  pr->pr_width  +  10; 


/*  center  the  yes/no  or  ok  buttons  under  the  message  */ 
r  “  (Rect  *)  panel_get (message_item,  PANEL_ITEM_RECT) ; 
left  =  (r->r_width  -  width)  /  2; 
if  (left  <  0) 
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left  =  0; 

top  =  rect_bottom(r)  +5; 


if  (ok_only)  { 

panel_create_item (panel,  PANEL_BUTTON , 

PANEL_ITEM_X,  left,  PANEL_ITEM_Y,  top, 

PANEL_LABEL_IMAGE,  pr, 

PANEL_CLIENT_DATA,  1, 

PANEL_NOTIFY_PROC,  yes_no_ok, 

0); 

}  else  { 

pane l_create_i tern (panel ,  PANEL_BUTTON , 

PANEL_ITEM_X,  left,  PANEL_ITEM_Y,  top, 

PANEL_LABEL_IMAGE,  pr, 

PANEL_CLIENT_DATA,  0, 

PANEL_NOTIFY_PROC,  yes_no_ok, 

0); 

panel_create_itein  (panel ,  PANEL_BUTTON , 

PANEL_IiABEL_IMAGE,  panel_button_image  (panel,  "Confirm”,  8,  0)  , 
PANEL_CLIENT_DATA,  1, 

PANEL_NOTIFY_PROC,  yes_no_ok, 

0); 

} 

window_fit (panel) ; 

window  fit (confirmer) ; 


/*  center  the 
r  = 
width  = 
height  = 


confirmer  frame  on  the  screen  */ 

(Rect  *)  win dow_get  (confirmer,  WIN_SCREEN__RECT)  ; 
(int)  window_get (confirmer,  WIN_WIDTH) ; 

(int)  window_get (confirmer,  WIN_HEIGHT) ; 


left  =  (r->r_width  -  width)  /  2; 

top  =  (r->r_height  -  height)  /  2; 

if  (left  <  0) 
left  =  0; 
if  (top  <  0) 
top  =0; 

window  set (confirmer,  WIN_X,  left,  WIN_Y,  top,  0) ; 


return  confirmer; 

} 

static  void 
yes_no_ok (item,  event) 

Panel_item  item; 

Event  * event; 

{ 

window_return (panel_get (item,  PANEL_CLIENT_DATA) ) ; 

} 
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A.2.  image _browser_l  The  following  program  is  discussed  in  Chapter  4,  Using  Windows.  It  lets  the 

user  browse  through  icons  and  display  them.  It  shows  a  more  complex  subwin¬ 
dow  layout. 
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/***************************************************************************/ 
/*  image_browser_l . c  */ 

/***************************************************************************/ 

#include  <suntool/sunview.h> 

#include  < sunt ool /panel .h> 

#include  <suntool/tty .h> 

#include  <stdio.h> 

♦include  <suntool/icon_load.h> 

♦include  <suntool/seln.h> 

Frame  frame; 

Panel  control_panel ,  display_panel; 

Tty  tty; 

Panel_item  dir_item,  fname_item,  image_item; 

ls_proc  0  ,  show_proc  ()  ,  quit_proc  () ; 

char  *get_selection (> ; 

♦define  MAX_PATH_LEN  1024 
♦define  MAX_FILENAME_LEN  256 

main(argc,  argv) 
int  argc; 
char  **argv; 

{ 

frame  =  window_create <NULL,  FRAME, 

FRAME_ARGS,  argc,  argv, 

FRAME_IiABEL,  "image_browser_l'' , 

0)  ; 

init_tty  ()  ; 
init_control_panel  () ; 
init_display_panel  ()  ; 
window_fit (frame) ; 
window_main_loop (frame) ; 
exit (0) ; 

} 

init_tty  () 

{ 

tty  =  win dow_create (frame,  TTY, 

WIN_COLUMNS,  30, 

WIN_R0WS,  20, 

0); 

} 
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init_control_panel  () 

{ 

char  *getwd(); 

char  current_dir [1024 ]  ; 

control_j>anel  =  window_create  (frame,  PANEL,  0); 

dir_item  =  panel_create_item(corrtrol_panel,  PANEL_TEXT, 
PANEL_VALOE_DISPLAY_LENGTH,  13, 

PANEL_LABEL_STRING,  "Dir:  ", 

PANEL_VALUE,  getwd (current_dir) , 

0); 


fname_item  =  panel_create_item(contr6l_panel,  PANEL_TEXT, 
PANEL_ITEM_X ,  ATTR_COL ( 0 ) , 

PANEL_ITEM_Y ,  ATTR_ROW (1 ) , 

PANEL_VALUE_DISPLAY_LENGTH,  13, 

PANEL_LABEL_STRING,  "File:", 

0)  ; 


panel_create_item  (control_panel ,  PANEL_BUTTON, 


PANEL_ITEM_X, 
PANEL_ITEM_Y, 
PANEL_LABEL_IMAGE , 
P ANEL_NOT I FY_PR0C , 
0); 


ATTR_COL(0)  , 

ATTR_ROW(2), 

parrel_button_image  (control_panel,  "List",  0,  0)  , 
ls_proc. 


panel_create_item  (control_panel ,  PANEL_BDTTON, 

PANEL_LABEL_IMAGE ,  panel_button_image (control_panel , "Show", 0, 0) , 
PANEL_NOTIFY_PROC,  show_jproc, 

0); 


panel_create_item  (control_panel ,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE ,  panel_button_image (control_panel, "Quit", 0, 0) , 
PANEL_NOTIFY_PROC,  quit_proc, 

0); 

window  fit (control_panel} ; 
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ls_proc  0 

{ 

static  char  previous_dir [MAX_PATH_LEN] ; 
char  *current_dir; 
char  cmdst ring [100]; 

current_dir  =  (char  *) panel_get_value (dir_item} ; 

if  (strcmp (current_dir ,  previous_dir) )  { 
chdir (current_dir) ; 

sprintf (cradstring,  "cd  %s\n",  current_dir> ; 
ttysw_input  (tty,  cmdstring,  strlen (cmdstring) ) ; 
strcpy (previous_dir,  current_dir) ; 

} 

sprintf (cmdstring,  "Is  -1  %s\n",  panel_get_value (fname_item) ) ; 
ttysw_input (tty,  cmdstring,  strlen (cmdstring) ) ; 

} 

quit_proc ( ) 

{ 

window_destroy (frame) ; 

} 

show__proc() 

{ 

char  * filename; 

if  (! strlen (filename  =  get_selection () ) ) 
return; 

load_image (filename) ; 

} 

load_image (filename) 
char  *filename; 

{ 

Pixrect  * image; 

char  error_msg [IL_ERRORMSG_SIZE] ; 

if  (image  =  icon_load_mpr (filename,  error_msg) )  { 
panel_set (image_item, 

PANEL_ITEM_X ,  ATTR_COL ( 5 ) , 

PANEL_ITEM_Y ,  ATTR_ROW ( 4 ) , 

PANEL_LABEL_IMAGE,  image, 

0); 

} 

} 
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init_display_panel () 

{ 

display_jpanel  =  window_create  {frame,  PANEL, 

WIN_BELOW,  control_panel, 

WIN_RIGHT_OF,  tty, 

0)  ; 

image_item  =  panel_create_item(display_panel,  PANEL_MESSAGE,  0); 

} 

char  * 

get_selection 0 

{ 

static  char  filename [MAX_FILENAME_LEN] ; 

Seln_holder  ^Ider; 

Seln_reqpest  *buffer; 

holder  =  seln__inquire  (SELN_PRIMARY)  / 

buffer  =  seln_ask(&holder,  SELN_REQ_CONTENTS_ASCII,  0,  0) ; 

strncpy (filename,  buffer->data  +  sizeof  (Seln_attribute) ,  MAX_FILENAME__LEN) ; 
return  (filename) ; 
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The  following  program  is  discussed  in  Chapter  4,  Using  Windows.  It  is  a  more 
complex  icon  browser  than  the  previous  example  It  illustrate  how  you  can  use 
row! column  space  to  specify  the  size  of  a  subwindow. 


Appendix  A  —  Example  Ptograms  {image_browser_2)  407 


/****■***********************************************************************/ 
#ifndef  lint 

static  char  sccsid[]  =  "@ (#) image_browser_2 . c  1.3  86/09/15  Copyr  1986  Sun  Micro"; 
tendif 

/■kic***************  **********************************************************  / 

♦include  <suntool/sunview.h> 

♦include  < sun tool /panel .h> 

♦include  <suntool/tty.h> 

♦include  <stdio.h> 

♦include  <suntool/icon_load.h> 

♦include  <suntool/ seln .h> 

♦include  <suntool/expand_name.h> 

♦include  <suntool/scrollbar.h> 

static  char  namebuf [100] ; 

static  int  file_count,  image_count; 

static  struct  namelist  *name_list; 

♦define  get_name(i)  name_list->names [ (i) ] 

Frame  frame; 

Panel  contro Impanel,  display_panel; 

Tty  tty; 

Panel_item  dir_item,  fname_item,  image_item; 

show_proc{),  browse_proc { ) ,  quit_proc(); 

Pixrect  *get_image  () ; 

char  *get_selection () ; 

♦define  MAX_PATH_LEN  1024 
♦define  MAX_FILENAME_LEN  256 

main (argc,  argv) 
int  argc; 
char  **argv; 

{ 

frame  =  window_c reate (NULL,  FRAME, 

FRAME_ARGS,  argc,  argv, 

FRAME_LABEL,  " image_browser_2 " , 

0); 

init_control_panel () ; 
init_display_panel () ; 
window_set (control  jjanel, 

WIN_WIDTH,  window_get {display_panei,  WIN_WIDTH,  0), 

0); 

window_fit (frame) ; 
window_main_loop (frame) ; 
exit (0) ; 

} 
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init_control_jpanel  (} 

{ 

char  current_dir  [MAX_PATH_IiEN]  ; 

controlj)anel  =  winciow_c reate  (frame,  PANEL,  0); 

dir_item  =  panel_create_item (control_panel,  PANEL_TEXT, 

PANEL_LABEL_X ,  ATTR_COL ( 0 ) , 

P ANEL_LABEL_Y ,  ATTR_ROW ( 0 ) , 

PANEL_VALUE_DISPLAY_LENGTH,  2  3 , 

PANEL_VALUE,  getwd (current_dir) , 

PANEL__LABEL_STRING,  "Dir:  ", 

0)  ; 

(void)  panel_create_item (control_panel,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE ,  panel_button_itnage  (control_jpanel,  "Browse"  ,0,0)  , 
PANEL_NOTIFY_PROC,  browse_proc, 

0); 

fname_item  =  panel_create_item {control_panel ,  PANEL_TEXT, 
PANEL_LABEL_X,  ATTR_COL (0 ) , 

PANEL_LABEL_Y ,  ATTR_ROW ( 1 )  , 

PANEL_yALUE_D I SPLAY_LENGTH ,  23, 

PANEL_LABEL_STRING,  "File : " , 

0); 

(void)  panel_create_item (control_panel,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE,  panel_button_iinage  (control_panel,  "Quit",  6,  0)  , 
PANEL_NOTIFY_PROC,  quit_proc, 

0)  ; 

window_fit_height  (control_panel)  ; 

window_set (control_panel,  PANEL_CARET_ITEM,  fname_item,  0); 
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browse_jproc  () 

{ 

Panel_item  old_item; 
register  int  i; 
int  len; 

Pixrect  * image; 

int  previous_image_count; 

register  int  row,  col; 

set_directory  (} ; 
match_files () ; 

panel_each_item (display_panel,  old_item) 

pr  destroy  ((Pixrect  *)  panel_get  (old_item,  PANEL_IiABEL_IMAGE)  )  ; 
panel_free (old_item)  ; 
panel_end_each 

previous_image_count  =  image_count; 

for  (row  =  0,  image_count  =  0;  iinage_count  <  file_count;  row++) 
for  (col  =  0;  col  <  4  &&  image_count  <  file_count;  col++)  { 
if  (image  =  get_image (image_count ) )  { 

panel_creat e_item  ( display_panel ,  PANEL_MESSAGE , 

PANEL_ITEM_y,  ATTR_R0W (row) , 

PANEL_ITEM_X,  ATTR_C0L (col) , 

PANEL_LABEL_IMAGE,  image,  0) ; 

image_count++; 

} 

} 

if  (image_count  <=  previous_image__count) 

panel_update_scrolling_size (display_jpanel) ; 

panel_j)aint  (display_panel,  PANEL_CLE:AR)  ; 

free_namelist (name_list) ; 

} 

set_directory ( ) 

{ 

static  char  previous_dir [MAX_PATH_LEN] ; 
char  *current_dir; 

current_dir  =  (char  *) panel_get_value (dir_item) ; 

if  (strcmp (current_dir,  previous_dir) )  { 
chdir (current_dir) ; 
strcpy (previous_dir,  current_dir) ; 

1 

} 

Pixrect  * 
get_image (i) 
int  i  ; 

{ 

char  error_msg [ IL_ERRORMSG_SIZE] ; 

return  (icon_load_mpr (get_name (i) ,  error_msg) ) ; 

} 
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mat ch_f lies (} 

{ 

char  *val; 


val  =  (char  *) panel_get_value (fname_item) ; 
strcpy (namebuf ,  val); 
name_list  =  expand_name (namebuf ) ; 
file  count  =  name  list->count; 


quit_proc  () 

{ 

window_destroy (frame) ; 

} 

show_proc  0 

{  -  -  * 

char  *filename; 

if  (! strlen (filename  =  get_selection () ) ) 
return; 

load_image (filename) ; 

} 

load_image (filename) 
char  *filename; 

{ 

Pixrect  * image; 

char  e r ro r_ms g [ I L_ERRORMSG_S I ZE ] ; 

if  (image  =  icon_load_npr (filename,  error_msg) )  { 
panel_set (image_item, 

PANEL_ITEM_X,  ATTR_COL(5), 

PANEL_ITEM_Y ,  ATTR_R0W ( 4 ) , 

PANEL_IiABEL_IMAGE ,  image, 

0); 

} 

} 
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init_display_panel () 

{ 

int  width; 

Scrollbar  sb  =  scrollbar_create (SCROLL_MARGIN, 10, 0) ; 
width  =  (int) scrollbar_get (sb,  SCROLL_THICKNESS,  0) ; 
display_panel  =  window_create (frame,  PANEL, 


WIN_BEL0W, 
WIN  X, 


control_panel , 

0, 


WIN_VERTICAL_SCROLLBAR,  sb, 
WIN_ROW_HEIGHT,  64, 

WIN_COLUMN_WIDTH,  64, 

WIN_ROW_GAP,  10, 

WIN_C0L0MN_GAP,  10, 

WIN_LEFT_MARGIN,  width  +  10, 

WIN_TOP_MARGIN ,  1 0 , 

WIN_R0WS,  4, 

WIN_COLUMNS,  4, 

0); 

window_set (display_j3anel,  WIN_LEFT_MARGIN,  10,  0); 


char  * 

get_se lection  0 


static' char 
Seln_holder 
Seln  request 


filename [MAX_FILENAME_LEN] ; 
holder; 

*buffer; 


holder  ==  seln_inquire  (SELN_PRIMARY)  ; 

buffer  =  seln_ask(&holder,  SELN_REQ_CONTENTS_ASCII,  0,  0); 

strncpy  (filename,  buffer- >data  +  sizeof  (Seln_attribute)  ,  MAX_FILENAME_IiEN)  ; 
return  (filename) ; 
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A.  4.  tty  Jo  The  following  program  demonstrates  the  use  of  ttysw_input  ( ) , 

tt  Ysw_output  ( )  and  TTY  escape  sequences.  These  functions  are  explained 
in  Chapter  11,  TTY  Subwindows. 

tty  Jo  creates  a  panel  and  a  tty  subwindow.  You  can  send  arbitrary  character 
sequences  to  the  latter  as  input  or  output  by  manipulating  panel  items.  There  is 
also  a  button  that  sends  the  current  time  within  the  escape  sequence  to  set  the 
frame  label.  Try  sending  different  sequences  to  the  tty  subwindow.  Press 
CTRL-R  to  see  the  difference  between  what  appears  on  the  screen  and  what  was 
input  to  the  pseudo-tty.  Also  try  starting  the  tool  with  a  program  such  as  vi  as  a 
command  line  argument. 
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#ifndef  lint 

static  char  sccsid[]  =  "@ (#) tty_io. c  1.4  87/11/19  Copyr  1986  Sun  Micro"; 
tendif 

^■k'k'kit'k'k’k'k'k'k'k-k'k’kick'k'k'k’k'k  ★  *  ■k-k'k-kiiicie'k'kii’k'kici^'ki^’ki^it'kick’k'k’k'k-kiv'k'k-kifk’kic'k'kif-kic'k'k'k'kicitic'k'k'k'kic'kic^ 

finclude  <stdio.h> 

#include  <suntool/sunview.h> 
finclude  <suntool/tty .h> 
finclude  <suntool/pan6l .h> 

fdefine  TEXT_ITEM_MAX_LENGTH  25 


Tty 

Panel_item 

char 

static  void 
static  void 
static  void 


tty; 

text_item; 
tmp_buf [80]; 

input_text ()  ; 
output_text  0 
output_time () 


argv) 

argc  ; 

**argv; 

frame; 
panel; 

frame  =  window_create (NULL,  FRAME, 

FRAME_ARGS, 

WIN_ERROR_MSG, 

0); 

panel  =  window_create (frame,  PANEL,  0) ; 

/*  set  up  a  simple  panel  subwindow  */ 

panel_create_item  (panel ,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE,  panel_button_image (panel,  "Input  text",  11,  0), 
PANEL_NOTIFY_PROC ,  input^text , 

0); 

panel_creat e_item  (panel ,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE,  panel_button_image (panel,  "Output  text",  11,  0) , 
PANEL_NOTIFY_PROC ,  output_t ext , 

text_item  =  panel_create_item (panel,  PANEL_TEXT, 

PANEL_LABEL_STRING,  "Text;", 

PANEL_VALDE,  "Hello  hello", 

P ANEL_VALUE_D I SP  LAY_LENGTH ,  TEXT_I TEM_MAX_LENGTH , 

0); 

panel_create_item (panel,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE,  panel_button_image (panel,  "Showtime",  11,  0), 
PANEL_NOTIFY_PROC,  output_time, 

0)  ; 


argc,  argv, 

"Can't  create  tool  frame". 


main  (argc, 
int 
char 

{ 

Frame 

Panel 


window_fit_height (panel) ; 
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/*  Assume  rest  of  arguments  are  for  tty  subwindow,  except  FRAME_ARGS  leaves  the 
*  program_name  as  argv[0],  and  we  don't  want  to  pass  this  to  the  tty  subwindow. 
*/ 

argv++; 

tty  =  window_create (frame,  TTY, 

TTY_ARGV,  argv, 

WIN_ROWS,  24, 

WIN_COLUMNS,  80, 

0); 

window_fit (frame) ; 

ttysw_input (tty,  "echo  my  pseudo-tty  is  'tty'\n",  28); 

window_main_loop (frame) ; 
exit(O); 


static  void 

in^ut_t ext  (item,  event) 

Panel_item  item; 

Event  * event; 

{ 

strcpy (tmp_buf ,  (char  *)  panel_get_value (text_item) ) ; 
ttysw_input  (tty,  tmp_buf,  strlen (tmp_buf ) ) ; 


static  void 

output_text (item,  event) 

Panel_item  item; 

Event  * event; 

{ 

strcpy (tmp_buf,  (char  *)  panel_get_value (text_item) ) ; 
ttysw_output (tty,  tmp_buf ,  strlen (tmp_buf ) ) ; 
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static  void 

output_time (item,  event) 

Panel_item  item; 

Event  * event; 

{ 

#include  <sy s/time. h> 

#define  ASCTIMELEN  26 

struct  timeval  tp; 

/*  construct  escape  sequence  to  set  frame  label  */ 
tmp_buf[0]  -  '\033'; 
tmp_buf [ 1 ]  =  ' ] ' ; 
tmp_buf  [  2  ]  =  '  1  ; 

tmp_buf[2  +  ASCTIMELEN  +  1]  =  '\033'; 
tmp_buf[2  +  ASCTIMELEN  +  2]  =  '  ; 

gettimeof day {&tp,  NULL); 

strncpy (&tmp_buf [3] ,  ctime (&tp. tv_sec)  ,  ASCTIMELEN) ; 
ttysw_output  (tty ,  tmp_buf,  ASCTIMELEN  +  5); 

} 

^ _ _ _ / 
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A,5.  fontjnenu 


\  i 

The  next  fontjnenu,  builds  on  several  of  the  examples  given  in  Giapter 

12,  Menus.  Examples  of  the  font  menu  it  creates  are  shown  below: 


t 


Revision  A,  of  May  9, 1988 


Appendix  A  —  Example  Programs  (fontjnenu)  AY! 


/*****************************************************************************/ 

#ifndef  lint 

static  char  sccsid[]  =  "@ (#) font_menu . c  1.2  86/09/15  Copyr  1986  Sun  Micro"; 

#endif 

/*****************************************************************************/ 

#include  <suntool/sunview .h> 

#include  <suntool/panel .h> 

#include  <suntool/walkmenu.h> 

void  set_familyO,  set_size(},  set_on_off  ()  ,  toggle_on_off  ()  ,  open_fonts  ()  ; 

Menu  new_menu(),  initialize_on_of f () ; 
char  *int_to__str  0  ; 
extern  char  *  sprintf () ; 
extern  char  *  mallocO; 

Panel_itein  f eedback_item; 

char  *family,  *size,  *bold,  *italic; 

Pixfont  *cour,  *serif,  *apl,  *cnir,  *screen; 

/*****************************************************************************/ 

/*  main  */ 

/*  First  create  the  base  frame,  the  feedback  panel  and  feedback  item.  The  */ 

/*  feedback  item  is  initialized  to  "gallant  8".  */ 

/*  Then  get  the  frame's  menu,  call  new_menu()  to  create  a  new  menu  with  the  */ 

/*  original  frame  menu  as  a  pullright,  and  give  the  new  menu  to  the  frame.  */ 

/*****************************************************************************/ 

main (argc,  argv) 
int  argc; 
char  *argv [ ] ; 

{ 

Frame  frame; 

Panel  panel; 

Menu  menu; 
int  defaults; 

frame  =  win dow_create (NULL,  FRAME,  FRAME_LABEL,  "Menu  Test  —  Try  frame  menu.",  0) ; 
panel  =  window_create (frame,  PANEL,  WIN_R0WS,  1,  0); 

f eedback_item  =  panel_create_item (panel,  PANEL_MESSAGE,  PANEL_LABEL_STRING,  "",  0) ; 

family  =  "Gallant",  size  =  "8",  bold  =  italic  =  ""; 
update_feedback  ()  ; 

/*  remember  if  user  gave  -d  flag  */ 

if  (argc  >=  2)  defaults  =  strcmp (argv[l] ,  "-d")  ==  0; 

menu  =  (Menu) window_get (frame,  WIN_MENU) ; 
menu  =  new_menu (menu,  defaults); 
window^set (frame,  WIN_MENU,  menu,  0) ; 

window_main_loop (frame) ; 
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/*****************************************************************************/ 
/*  new_nienu  —  returns  a  new  menu  with  'original  menu'  as  a  pullright.  */ 

/************************************★****************************************/ 

Menu 

new_menu (original_menu,  defaults) 

Menu  original_menu; 
int  defaults; 

{ 

Menu  new_menu,  family_menu,  size_menu,  on_off_menu; 
int  i  ; 

/*  create  the  on-off  menu,  which  will  be  used  as  a  pullright 
*  for  both  the  bold  and  italic  items  to  the  new  menu. 

*/ 

on_off_menu  =  menu_create (MENU_STRING_ITEM,  "On",  1, 

MENU_STRING_ITEM,  "Off",  0, 

MENU_GEN_PROC,  initialize_on_of f , 

MENU_NOTIFY_PROC,  set_on_off, 

0); 

/*  create  the  new  menu  which  will  eventually  be  returned  */ 

open_fonts 0 ;  /*  first  open  the  needed  fonts  */ 
new_menu  =  menu_create ( 

MENU_PULLRIGHT_ITEM, 

"Frame", 
or iginal_menu , 

MENU_PULLRIGHT_ITEM, 

"Family" , 

family_menu  =  menu_create ( 

MENU_ITEM, 

MENU_STRING,  "Courier", 

MENU_F0NT,  cour, 

0, 

MENa_ITEM, 

MENU_STRING,  "Serif", 

MENU_F0NT,  serif, 

0, 

MENU_ITEM, 

MENU_STRING,  "aplAPLGIJ", 

MENU_F0NT,  apl, 

MENU_ITEM, 

MENU_STRING,  "CMR", 

MENU_F0NT,  cmr, 

0, 
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MENO_ITEM, 

MENa_STRING,  "Screen", 
MENU_FONT,  screen, 

0, 

MENU  NOTIFY  PROC,  set  family. 


0), 

MEND_PULLRIGHT_ITEM 
"Size",  size_menu 
MENU_ITEM, 
MENU_STRING, 
MENU_PULLRIGHT, 
MENU_N0T IF Y_PROC , 
MENU_CLIENT_DATA, 

0,  X 

MENU_ITEM, 
MENU_STRING, 
MENU_PULLRIGHT, 
MENU_NOTIF Y_PR0C , 
MENU_CLIENT_DATA, 
0, 

0); 


=  menu_c reate (0) , 

"Bold", 
on_of f _menu , 
toggle_on_of f , 
Sbold, 

"Italic"^ 
on_o  f  f _menu , 
toggle_on_of  f , 
Sitalic, 


/*  give  each  item  in  the  family  menu  the  size  menu  as  a  pullright  */ 
for  (i  =  (int) menu_get (family_menu,  MENU_NITEMS) ;  i  >  0;  — i> 
menu_set (menu_get (family_menu,  MENU_NTH_ITEM,  i) , 

MEND_PULLRIGHT,  size_menu,  0); 

/*  put  non-selectable  lines  inbetween  groups  of  items  in  family  menu  */ 
menu_s  et ( f ami ly_menu , 

MENU_INSERT,  2,  menu_create_item <MENU_STRING,  " - ", 

MENU_INACT I YE ,  TRUE , 

0), 

0); 

menu_set (family_menu, 

MENU_INSERT,  5,  menu_get (family_menu,  MENU_NTH_ITEM,  3), 

0}; 


j 


/*  The  size  menu  was  created  with  no  items.  Now  give  it  items  representing  */ 
/*  the  point  sizes  8,  10,  12,  14,  16,  and  18.  */ 

for  (i  =  8;  i  <=  18;  i  +=  2) 

,  menu_set (size_menu,  MENU_STRING_ITEM,  int_to_str (i) ,  i,  0); 

/*  give  the  size  menu  a  notify  proc  to  update  the  feedback  */ 
menu_set  (size_menu,  MENU_NOTIFY_PROC,  set_size,  0); 
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/*  if  the  user  did  not  give  the  -d  flag,  make  all  the  menus  come 

*  up  with  the  initial  and  default  selections  the  last  selected 

*  item,  and  the  initial  selection  selected. 

*/ 

if  ([defaults)  { 

menu_set (new_menu, 

MENU_DEFAULT_SELECTION ,  MENU_SELECTED , 

MENU_I NI TI AL_SELECT I ON ,  MENO_SELECTE  D , 
MENU_INITIAL_SELECTION_SELECTED ,  TRUE , 

0); 

menu_set (f amily_menu , 

MENU_DEFAULT_SELECTION,  MENU_SELECTED , 
MENU_INITIAL_SELECTION,  MENU_SELECTED, 
MENU_INITIAL_SELECTION_SELECTED,  TRUE, 

0); 

menu_set  (size_menu, 

MENU_DEFAULT_SELECT I ON ,  MENU_SELECTE  D , 
MENU_INITIAL_SELECTION,  MENU_SELECTED , 
MENU_INITIAL_SELECTION_SELECTED,  TRUE, 

0); 

menu_set (on_of f_menu, 

MENU_DEFAULT__SELECTION,  MENU_SELECTED , 
MENU_INITIAL_SELECTION,  MENU_SELECTED , 
MENU_INITIAL_SELECTION_SELECTED ,  TRUE, 

0); 


return  {new_menu); 

} 
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/*  set_fainily  —  notify  proc  for  family  menu.  Get  the  current  family  and  */ 
/*  display  it  in  the  feedback  panel.  Note  that  we  first  get  the  value  */ 
/*  of  the  menu  item.  This  has  the  side  effect  of  causing  any  pullrights  */ 
/*  further  to  the  right  of  mi  to  be  evaluated.  Specifically,  the  value  of  */ 
/*  each  family  item  is  the  value  of  its  pullright  —  namely  the  size  menu.  */ 
/*  When  the  size  menu  is  evaluated,  the  notify  proc  set__size()  is  called,  */ 
/*  which  updates  the  feedback  for  the  size.  */ 


/*****************************************************************************/ 

/*ARGSUSED*/ 

void 

set_family  (m,  mi) 

Menu  m; 

Menu_item  mi; 

{ 

menu_get(mi,  MENU_VALUE) ;  /*  force  pullrights  to  be  evaluated  */ 

family  =  menu_get (mi,  MENU_STRING) ; 
update_f eedback ( > ; 

} 

/*****************************************************************************/ 
/*  set_size  —  notify  proc  for  the  size  menu.  */ 

/*****************************************************************************/ 

/*ARGSUSED*/ 

void 

set__size  (m,  mi) 

Menu  m; 

Menu_item  mi; 

{ 

size  =  menu_get(mi,  MENU_STRING)  ; 
update_f eedback () ; 

} 
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/*  initial ize_on_off  —  generate  proc  for  the  on_off  menu.  */ 
/*  The  on-off  menu  is  a  pullright  of  both  the  bold  and  the  italic  menus.  */ 
/*  We  want  it  to  toggle  —  if  its  parent  was  on,  it  should  come  up  with  */ 
/*  "Off"  selected,  and  vice-versa.  We  can  do  that  by  first  getting  the  */ 
/*  parent  menu  item,  then,  indirectly  through  its  client  data  attribute,  */ 
/*  seeing  if  the  string  representing  the  bold  or  italic  state  is  null.  */ 
/*  If  the  string  was  null,  we  set  the  first  item  ("On")  to  be  selected,  */ 
/*  else  we  set  the  second  item  ("Off")  to  be  selected.  */ 


/*****************************************************************************/ 

Menu 

initialize_on_of f (m,  op) 

Menu  m;  Menu_generate  op; 

{ 

Menu_item  parent_mi; 
char  **name; 

if  (op  !=  MENU_CREATE)  return  (m)  ; 

parent_mi  =  (Menu_item)  menu_get  (m,  MENO_PARENT)  ; 
name  =?  (char  *  * )  menu_get  (parent_mi ,  MENU_CLIENT_DATA)  ; 

if  (**name  ==  NULL) 

menu_set  (m,  MENU_SELECTED,  1,  0); 

else 

menu_set (m,  MENU_SELECTED,  2,  0)  ; 
return  (m) ; 

} 
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/*  set_on_off  —  notify  proc  for  on-off  menu.  */ 
/*  Set  the  feedback  string  —  italic  or  bold  —  appropriately  depending  on  */ 
/*  the  current  setting.  Note  that  the  "On"  item  was  created  to  return  a  */ 
/*  value  of  1,  and  the  "Off"  item  will  return  a  value  of  0.  */ 


/*************************************  *  *  **************************************/ 
void 

set_on_off  (m,  mi) 

Menu  m;  Menu_item  mi; 

{ 

Menu_item  parent_mi; 
char  **name; 

parent_mi  =  (Menu_item)  menu_get (m,  MENU_PARENT) ; 
name  =  (char  **}menu_get (parent_mi,  MENO_CLIENT_DATA) ; 
if  (menu_get (mi,  MENU_VALUE) ) 

*name  =  (char  * ) menu_get (parent_mi,  MENU_STRING) ; 

else 

*name  =  ” ” ; 
update_f eedback ( ) ; 

} 

/************************★****************************************************/ 
/*  toggle_on_off  —  notify  proc  for  the  "Bold"  and  "Italic"  menu  items.  */ 

/*  Using  a  notify  proc  for  the  menu  item  allows  toggling  without  bringing  */ 

/*  up  the  on-off  pullright.  */ 

/**************'**Tfr********^**lfr********l*r*'fr****************’*********************/ 

/*ARGSUSED*/ 

void 

toggle_on_of  f  (m,  mi) 

Menu  m; 

Menu__item  mi; 

{ 

char  **name; 

name  =  (char  * * ) menu_get (mi ,  MENU_CLIENT_DATA) ; 
if  (**name  ==  NULL) 

*name  =  (char  *)menu_get (mi,  MENU_STRING) ; 

else 

*name  =  "  " ;. 
update_f eedback ( ) ; 

} 
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update_feeciback  0 

{ 

char  buf [30] ; 

sprint  f  (buf,  ''%s  %s  %s  %s",  bold,  italic,  family,  size); 
panel_set  (feedback_item,  PANEL_IjABEL_STRING,  buf,  0); 

} 

char  * 

int_to_str (n) 

{ 

char  *r  =  malloc(4); 
sprintf (r,  "%d",  n) ; 
return  (r> ; 

} 


void 

open_fonts() 

{ 

cour  =  pf_open  (”/usr/lib/fonts/fixedwidthfonts/cour . r. 10") ; 
serif  =  pf_open ("/usr/lib/fonts/fixedwidthfonts/serif . r. 10") ; 
apl  =  pf_open ("/usr/lib/fonts/f ixedwidthfonts/apl .r . 10") ; 
cmr  =  pf_open ("/usr/lib/fonts/fixedwidthfonts/cmr.b. 8") ; 
screen  =  pf_open ("/usr/lib/fonts/fixedwidthfonts/screen. r. 11") 


} 
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A.6.  resize _demo  This  program  demonstrates  how  to  resize  the  subwindows  of  a  frame  yourself  if 

you  need  to  use  a  complicated  topology. 

The  particular  subwindow  layout  used  here  has  four  subwindows.  One  has  a 
fixed  width  and  height  in  pixels,  another  has  a  fixed  width  in  characters  (using 
the  user-set  default  font),  and  the  other  two  fill  up  the  empty  space.  One  of  the 
subwindows  also  has  a  scrollbar. 

This  program  interposes  in  front  of  the  frame’s  client  event  handler.  If  the  event 
is  WIN_RES  IZE,  the  program’s  own  r  esize  ( )  procedure  is  called,  which  sets 
the  subwindow  positions  explicitly. 

For  a  discussion  of  interposing  and  the  Notifier,  see  Chapter  17,  The  Notifier. 

The  simpler  case  of  using  window  attributes  to  layout  subwindows  is  described 
under  Explicit  Subwindow  Layout  in  Chapter  @NumberOf(window), 

@T itleOfiwindow ) . 
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#ifndef  lint 

static  char  sccsid[]  =  "%Z%%M%  %I%  %E%  Copyr  1986  Sun  Micro"; 
#endif 


#include  <suntool/sunview.h> 
#include  <suntool/canvas .h> 
#include  <suntool/ scrollbar .h> 


Canvas  Canvas_l,  Canvas_2,  Canvas_3,  Canvas_4; 
Pixwin  *Pixwin_l,  *Pixwin_2,  *Pixwin_3,  *Pixwin_4; 
Rect  framerect; 

PIXFONT  *font; 


extern  char  *  sprintf () ; 
/* 

*  font  macros: 

*  font_of fset (font) 

* 

* 

•k 

■k 

*  font_height (font) 

*/ 


gives  the  vertical  distance  between 
the  font  origin  and  the  ^op  left  corner 
of  the  bounding  box  of  the  string  displayed 
(see  Text  Facilities  for  Pixrects  in  the 
Pixrect  Reference  Manual) 
gives  the  height  of  the  font 


#define  font_of fset (font)  (-font->pf_char ['n' ] .pc_home.y) 

#define  font_height (font)  (font->pf_defaultsize .y) 


/* 

*  SunView-dependent  size  definitions 
*/ 


tdefine  LEFT_MARGIN  5 

#define  RIGHT_MARGIN  5 

#define  BOTTOM_MARGIN  5 

#define  SUBWINDOW  SPACING  5 


/*  margin  on  left  side  of  frame  */ 
/*  margin  on  right  side  of  frame  */ 
/*  margin  on  bottom  of  frame  */ 

/*  space  in  between  adjacent 
subwindows  * / 


/* 

*  application-dependent  size  definitions 


*/ 

#define  CANVAS_1_WIDTH  320 
#define  CANVAS_1_HEIGHT  160 
#define  CANVAS  3  COLUMNS  30 


/*  width  in  pixels  of  canvas  1  */ 

/*  height  in  pixels  of  canvas  1  */ 

/*  width  in  characters  of  canvas  3  */ 


main (argc,  argv) 
int  argc; 
char  **argv; 

{ 

Frame  frame; 

static  Notify_value  catch_resize () ; 

static  void  draw_canvas_l  () ,  draw_canvas_3 () ; 

/* 

*  create  the  frame  and  subwindows,  and  open  the  font 
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*  no  size  attributes  are  given  yet  ^ 

*/ 

frame  =  window_create (NULL,  FRAME, 

FRAME_ARGS,  argc,  argv, 

WIN_ERROR_MSG,  "Can't  create  tool  frame", 

FRAME_IiABEL ,  "Resize  Demo", 

0>; 

Canvas_l  =  window_create (frame,  CANVAS, 

CANVAS_RESIZE_PROC,  draw_canvas_l , 

0}; 

Canvas_2  =  window_create (frame,  CANVAS, 

0); 

Canvas_3  =  window_create (frame,  CANVAS, 

WIN_VERTICAL_SCROLLBAR,  scrollbar_create ( 

SCR0LL_P  LACEMENT ,  SCROLL_EAST , 

0), 

CANVAS_RESIZE_PROC,  draw_canvas_3, 

0 )  ; 

Canvas_4  =  window_c reate (frame,  CANVAS, 

0); 

Pixwin_l  =  canvas_pixwin (Canvas_l) ; 

Pixwin_2  =  canvas_pixwin (Canvas_2) ; 

Pixwin_3  =  canvas_j>ixwin  (Canvas_3)  ; 

Pixwin_4  =  canvas_pixwin (Canvas_4)  ; 
font  =  pf_default () ; 

/* 

*  now  that  the  frame  and  font  sizes  are  known,  set  the  initial 

*  subwindow  sizes 
*/ 

resize (frame) ; 

/* 

*  insert  an  interposer  so  that  whenever  the  window  changes 

*  size  we  will  know  about  it  and  handle  it  ourselves 
*/ 

(void)  notify_interpose_event_func (frame,  catch_resize,  NOTIFY_SAFE) ; 
/* 

*  start  execution 
*/ 

window_main_loop (frame)  ; 
exit  (0) ; 


catch_resize 

interposed  function  which  checks  all  input  events  passed  to  the  frame 
for  resize  events;  if  it  finds  one,  resize ()  is  called  to  refit 
the  subwindows;  checking  is  done  AFTER  the  frame  processes  the 
event  because  if  the  frame  changes  its  size  due  to  this  event  (because 
the  window  has  been  opened  or  closed  for  instance)  we  want  to  fit 
the  subwindows  to  the  new  size 
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static  Notify_value 

cat ch_resize (frame,  event,  arg,  type) 

Frame  frame; 

Event  * event; 

Notify_arg  arg; 

Notify_event_type  type; 

{ 

Notify_value  value; 

value  =  notify_next_event_func (frame,  event,  arg,  type); 
if  (event_act ion (event)  ==  WIN_RESIZE) 
resize (frame) ; 
return (value) ; 


*  resize 

* 

*  fit  the  subwindows  of  the  frame  to  its  new  size 
*/ 

resize (frame) 

Frame  frame; 

{ 

Rect  *r; 

int  canvas_3_width;  /*  the  width  in  pixels  of  canvas  3  */ 

int  stripeheight;  /*  the  height  of  the  frame's  name  stripe  */ 

/*  if  the  window  is  iconic,  don't  do  anything  */ 

if  ( (int) win dow_get (frame,  FRAME_CLOSED ) ) 
return; 


/*  find  out  our  new  size  parameters  */ 

r  =  (Rect  *)  window_get (frame,  WIN_RECT) ; 
framerect  =  *r; 

stripeheight  =  (int)  window_get (frame,  WIN_TOP_MARGIN) ; 

canvas_3_width  =  CANVAS_3_C0LUMNS  *  font->pf_defaultsize.x 
+  (int)  scrollbar_ge"t  (SCROLLBAR,  SCROLL_THICKNESS)  ; 
window_set (Canvas_2, 

WIN_X,  0, 

WIN_Y,  0, 

WIN_WIDTH,  framerect .r_width  -  canvas_3_width 

-  LEFT_MARGIN  -  SUBWINDOW_SPACING 

-  RIGHT_MARGIN, 

WIN_HEIGHT,  framerect.r_height  -  CANVAS_1_HEIGHT 

-  stripeheight  -  SUBWINDOW_SPACING  - 
BOTTOM  MARGIN, 


WIN  HEIGHT, 


0)  ; 

window_set  (Canvas_l , 
WIN_X, 

WIN_Y, 

WIN  WIDTH, 


f ramerect . r_height  —  CANVAS_1_HEIGHT  - 
SDBWINDOW_SP AGING  -  stripeheight, 
CANVAS  1  WIDTH, 
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WIN_HEIGHT, 

0); 

window_set  {Canvas_4, 
WIN_X, 

WIN_Y, 

WIN  WIDTH, 


WIN_HEIGHT, 

0); 

window_5et (Canvas_3, 
WIN  X, 


WIN_Y, 
WIN_WIDTH, 
WIN  HEIGHT, 


CANVAS  1  HEIGHT, 


CANVAS_1_WIDTH  +  SUBWINDOW_SP AGING, 
framerect . r_height  -  CANVAS_1_HEIGHT 

-  SUBWINDOW_SP AGING  -  stripeheight , 
f ramerect . r_width  -  canvas_3_width 

-  CANVAS_1_WIDTH  -  LEFT_MARGIN 

-  2  *  SUBWINDOW_SPACING  -  RIGHT_MARGIN, 
CANVAS  1  HEIGHT, 


framerect . r_width  -  canvas_3_width 

-  LEFT_MARGIN  -  SUBWINDOW_SP AGING, 

0, 

can va  s_3_widt h , 

framerect . r_height  -  stripeheight 

-  BOTTOM  MARGIN, 


*  draw_canvas_l 

*  draw_canvas_3 

* 

*  draw  simple  messages  in  the  canvases 


static  void 
draw_canvas_l () 

{ 

char  buf [ 64 ] ; 

sprintf (buf ,  "%d  by  %d  pixels", 

CANVAS_1_WIDTH,  CANVAS_1_HEIGHT) ; 
pw_text (Pixwin_l ,  5,  font_offset (font) ,  PIX_SRC,  font, 

"This  subwindow  is  always  "); 

pw_text (Pixwin_l,  5,  font_offset (font)  +  font_height (font) , 

PIX  SRC,  font,  buf); 


static  void 
draw_canvas_3 () 

{ 

char  buf [64]; 


sprintf (buf,  "%d  characters  wide", 

CANVAS_3_C0LUMNS) ; 

pw_text  (Pixwin_3,  5,  f ont_off set (font) ,  PIX_SRC,  font, 

"This  subwindow  is  always  ") ; 

pw_text (Pixwin_3,  5,  font ^offset (font)  +  font_height (font) ,  PIX_SRC, 

font,  buf) ; 
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A.7.  detool  detool  is  a  simple  reverse-polish  notation  calculator  which  demonstrates  how  to 

use  pipes  to  write  a  SunView-based  front  end  for  an  existing  non-SunView  pro¬ 
gram.  detool  consists  of  a  panel  with  buttons  for  each  digit,  the  four  arithmetic 
operations,  and  an  enter  key.  The  digits  you  hit  are  displayed  in  a  message  item 
and  are  sent  via  a  pipe  to  ,dc(l)  a  UNIX  desk  calculator.  When  dc  computes  an 
answer,  it  is  sent  back  to  detool  via  a  second  pipe  and  it  is  displayed. 

Note  also  the  use  of  a  single  notify  procedure  for  aU  of  the  digit  buttons.  The 
actual  digit  associated  with  each  button  is  stored  as  the  client  data  for  each  panel 
item,  so  the  notify  procedure  can  determine  which  button  was  pressed  by  looking 
at  the  client  data.  This  value  is  then  passed  directly  to  dc.  The  operation  buttons 
also  all  use  a  single  notify  procedure. 

When  you  run  detool,  remember  that  it  is  a  reverse-polish  notation  calculator. 
For  instance,  to  compute  3*5  you  must  hit  the  buttons  3,  Enter,  5,  and  *  in  that 
order.  If  you  prefer  infix  notation,  you  could  easily  adapt  detool  to  use  bc(l) 
instead  of  dc. 
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#ifndef  lint 

static  char  sccsid[]  =  "@ (#) detool . c  1.4  86/09/15  Copyr  1986  Sun  Micro"; 
#endif 

/*******************■*********************************************/ 


#include  <stdio.h> 

#include  <suntool/sunview.h> 
finclude  <suntool/panel .h> 


static 

Frame 

frame; 

static 

Panel 

panel; 

static 

Panel 

item  digit  item [10] 

f 

enter  item; 

static 

Panel_ 

_item  add_item,  sub_ 

item,  mul  item,  div  item; 

static 

Panel_ 

item  display  item; 

static 

char 

display  buf[512] 

= 

"";  /*  storage  for  the 

*  numbers  currently  on 

*  the  display  (stored  as 

*  a  string)  */ 

static 

FILE 

*fp  tochild; 

/* 

fp  of  pipe  to  child  (write 

* 

data  on  it)  */ 

static 

FILE 

*fp  fromchild; 

/* 

fp  of  pipe  from  child  (read 

* 

data  from  it)  */ 

static 

int 

tochild; 

/* 

associated  file  descriptors  */ 

static 

int 

fromchild; 

static 

int 

childpid; 

/* 

pid  of  child  process  */ 

static 

int 

dead  =  6; 

/* 

set  to  1  if  child  process  has 

* 

died  */ 

main (arge,  argv) 

int 

arge; 

char 

**argv; 

{ 

static  Notify_value  pipe_reader () ; 
static  Notify_value  dead_child() ; 


frame  =  window__create  (NULL,  FRAME, 

FRAME_ARGS,  arge,  argv, 

WIN_ERROR_MSG,  "Cannot  create  frame",, 

FRAME_LABEL,  "detool  -  RPN  Calculator", 

0>  ; 

panel  =  window  create (frame,  PANEL, 

0)  ;  ^ 

create j>anel_items  (panel) ; 

window_fit (panel) ; 
window_fit (frame) ; 

/*  start  the  child  process  and  tell  the  notifier  about  it  */ 
start_dc  ( )  ; 

/* 

*  note  that  notify_set_input_func  takes  a  file  descriptor, 

*  not  a  file  pointer  used  by  the  standard  I/O  library 

j 
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*/ 

(void)  not ify_set_input_func (frame,  pipe_reader,  fromchild) ; 
(void)  notify_set_wait3_func (frame,  dead_child,  childpid) ; 

window_main_loop (frame) ; 
exit (0) ; 


static 

create_panel_items (panel) 

Panel  panel; 

{ 

int  c; 

char  name [2]; 

static  void  digit_proc ( )  ,  op_proc(); 

static  struct  { 

int  col,  row; 

}  positions [10]  =  { 


3  },  { 

0, 

0 

}, 

{ 

6, 

0 

{ 

12, 

0 

{ 

0, 

1 

}, 

{ 

6, 

1 

{ 

12, 

1 

{ 

0, 

2 

}r 

{ 

6, 

2 

{ 

12, 

2 

} 

}; 

name [1]  =  '  \0'  ; 

for  (c  =0;  c  <  10;  C++)  ( 
name [ 0 ]  =  c  +  'O'; 

digit  item[c]  =  pane l_create_item (panel,  P ANEL_BUTTON , 

PANEL_LABEL_IMAGE,  panel_button_image (panel,  name,  3,  0) , 
PANEL_NOTIFY_PROC,  digit_proc, 

PANEL_CLIENT_DATA,  (caddr_t)  (c  +  '0'), 

PANEL_LABEL_X,  ATTR_C0L (positions [ c ] . col ) , 

PANEL_LABEL_Y,  ATTR_R0W (positions [c] . row) , 

0); 

} 

add__item  =  panel_create_item (panel,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE ,  panel_button_image (panel,  "+",  3,  0), 
PANEL_NOTIFY_PROC,  op_proc, 

PANEL_CLIENT_DATA ,  ( caddr_t )  '  + ' , 

PANEL_LABEL_X ,  ATTR_COL (18), 

PANEL_LABEL_Y ,  ATTR_R0W ( 0 ) , 

0)  ; 

sub_item  =  panel_create_item (panel,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE,  panel_button_image (panel,  3,  0), 

PANEL_NOTIFY_PROC ,  op_proc , 

PANEL_CLIENT_DATA,  (caddr_t)  ' , 

PANEL_LABEL_X,  ATTR_COL (18), 

PANEL_LABEL_Y,  ATTR_R0W ( 1 ) , 

0)  ; 

mul_item  =  panel_create_item (panel,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE ,  panel_button_image (panel,  3,  0), 

P ANEL_N0T IFY_PR0C ,  op_proc , 

PANEL_CLIENT_DATA,  (caddr_t)  '*', 

PANEL_LABEL_X ,  ATTR_C0L (18), 

PANEL_LABEL_Y ,  ATTR_R0W ( 2 ) , 

0); 

div  item  =  panel_create_item (panel ,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE,  panel_button_image (panel,  "/",  3,  0), 
PANEL_NOTIFY_PROC ,  op_proc , 
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PANEL_CLIENT_DATA,  (caddr_t) 

PANEL_LABEL_X ,  ATTR_COL (18), 

PANEL_LABEL_Y ,  ATTR_ROW ( 3 ) , 

0); 

enter_item  =  panel_create_item (panel,  PANEL_BUTTON, 

PANEL_LABEL_IMAGE ,  panel_button_image (panel,  "Enter",  7,  0)  , 
PANEL__NOTIFY_PROC,  op_proc, 

PANEL_CLIENT_DATA,  (caddr_t)  '  ' , 

PANEL_LABEL_X ,  ATTR_C0L ( 6 ) , 

PANEL_LABEL_Y,  ATTR_R0W (3 ) , 

0); 

display_item  =  panel_create_item (panel,  PANEL_MESSAGE, 
PANEL_LABEL_STRING,  "0", 

PANEL_LABEL_X ,  ATTR_C0L ( 0 ) , 

PAlsIEL_LABEL_Y ,  ATTR_R0W  ( 4 )  , 

0); 


/*  callback  procedure  called  whenever  a  digit  button  is  pressed  */ 
static  void 

digit_proc (item,  event) 

Panel_item  item; 

Event  *event; 

{ 

int  digit_name  =  (int)  panel_get (item, 

PANEL_CLIENT_DATA) ; 

char  buf[2}; 

buf[0]  =  digit_name;  /*  display  digit  */ 

buf[l]  =  '\0'; 

streat (display_buf ,  buf) ; 

panel_set (display_item,  PANEL_LABEL_STRING,  display_buf ,  0)  ; 
send_to_dc (digit_name) ;  /*  send  digit  to  dc  */ 


*  callback  procedure  called  whenever  an  operation  button  is 

*  pressed 


static  void 
op_j)roc  (item,  event) 

Panel_item  item; 

Event  * event; 


op_name  =  (int)  panel_get (item, 

PANEL  CLIENT  DATA) ; 


display_buf [0]  =  '\0'; 

send_to_dc (op_name) ; 
if  (item  !=  enter_item) 
send_to_dc  ('  p'  )  ; 

send  to  dc ( ' \n' ) ; 


/*  don't  erase  display  yet;  wait 
*  until  the  answer  comes  back  */ 


/*  send  a  p  so  the  answer  will  be 
*  printed  by  dc  */ 
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/* 

*  start  the  child  process 
*/ 

static 
start_dc 0 
{ 

int  pipeto[2],  pipefromt2] ; 

int  c,  numfds; 

if  (pipe (pipeto)  <  0  ||  pipe (pipef rom)  <  0)  { 

perror ("detool")  ; 
exit(l); 

} 

switch  (childpid  =  fork())  { 
case  -1: 

perror ( "detool" ) ; 
exit (1) ; 

case  0:  /*  this  is  the  child  process  */ 

/* 

*  use  dup2  to  set  the  child' s  stdin  and  stdout  to  the 

*  pipes 
*/ 

dup2 (pipeto ( 0 ] ,  0  > ; 
dup2 (pipefrom[13 ,  1); 

/* 

*  close  all  other  fds  (except  stderr)  since  the  child 

*  process  doesn't  know  about  or  need  them 
*/ 

numfds  =  getdtablesize () ; 
for  (c  =  3;  c  <  numfds;  C++) 
close  (c); 

I 

/*  exec  the  child  process  */ 
execl ("/usr/bin/dc",  "dc",  0); 

perror ("detool  (child)");  /*  shouldn't  get  here  */ 

exit  ( 1 ) ; 

default:  /*  this  is  the  parent  */ 

close (pipeto [0] ) ; 
close (pipef rom[l] ) ; 
tochild  =  pipeto  [1]; 
fp_tochild  =  fdopen (tochild,  "w"); 
fromchild  =  pipefrom[0]; 
fp_fromchild  =  fdopen (fromchild,  "r")  ; 

/* 

*  the  pipe  to  dc  must  be  unbuffered  or  dc  will  not  get 

*  any  data  until  1024  characters  have  been  sent 
*/ 

setbuf (fp_tochild,  NULL) ; 
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break; 

} 

} 

/* 

*  notify  proc  called  whenever  there  is  data  to  read  on  the  pipe 

*  from  the  child  process;  in  this  case  it  is  an  answer  from  dc, 

*  so  we  display  it 
*/ 

static  Notify_value 

pipe_reader (frame,  fd) 

Frame  frame; 

int  fd; 

{ 

char  buf[512]; 

fgets (buf ,  512,  fp_f romchild) ; 

buf [strlen (buf )  -  1]  =  '\0';/*  remove  newline  */ 
panel_set (display_item,  PANEL_LABEL_STRING,  buf,  0) ; 
display_buf [0]  =  '\0'; 
return  (N0TIFY_D0NE} ; 

} 

/* 

*  notify  proc  called  if  the  child  dies 
*/ 

static  Notify_value 

dead_child (frame,  pid,  status,  rusage) 

Frame  frame; 

int  pid; 

union  wait  * status; 

struct  rusage  *rusage; 

{ 

panel_set (display_item,  PANEL_LABEL_STRING,  "Child  died! ",  0)  ; 
dead  =1; 

/* 

*  tell  the  notifier  to  stop  reading  the  pipe  (since  it  is 

*  invalid  now) 

*/ 

(void)  notify_set_input_func (frame,  NOTIFY_FUNC_NULL, 

fromchild) ; 

close (tochild) ; 
close (fromchild)  ; 
return  (N0TIFY_D0NE) ; 


/*  send  a  character  over  the  pipe  to  dc  */ 
static 

send_to_dc  (c) 

char  c; 

{ 

if  (dead) 

panel_set (display_item. 
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A.8.  typein 


This  program  shows  how  to  replace  the  functionality  of  the  Graphics  Tool  and 
gficsw  package  previously  available  under  SunWindows.  typein  provides  a  tty 
emulator  for  interaction  with  the  user  and  a  canvas  to  draw  on.  To  demonstrate 
it,  a  simple  application  is  included  which  allows  the  user  to  input  coordinates  in 
the  tty  emulator  and  then  draws  the  vectors  in  the  canvas. 

typein  uses  a  tty  subwindow  and  a  canvas.  Normally,  the  tty  subwindow  is  used 
to  allow  a  child  process  to  run  in  a  window;  in  this  case,  we  would  like  the  same 
process  to  write  in  that  window.  To  accomplish  this,  we  tell  the  tty  subwindow 
not  to  fork  a  child  process  with  the  tty__argv_do_not_fork  value  for 
TTY_ARGV.  typein  uses  dup2(2)  to  set  its  stdin  and  stdout  to  the  TTY__FD. 
When  the  user  types  something  in  the  tty  subwindow,  typein'^  read_input  ( } 
routine  is  called. 

NOTE  When  using  this  mechanism,  be  careful  of  the  following  problems.  First,  you 

must  use  the  Notifier  (unlike  the  old  gfxsw).  Second,  if  you  use  the  standard  I/O 
package,  be  sure  to  either  use  f  flush  carefuUy  or  to  remove  all  buffering  with 
setbuf  because  the  package  will  think  you  are  sending  data  to  a  file  and  not  to 
a  tty.  Finally,  be  sure  you  never  block  on  a  read  because  the  program  wiU  hang 
(either  use  non-blocking  I/O  or  only  read  one  line  at  a  time). 
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/*********************************************************/ 

#ifndef  lint 

static  char  sccsid[]  =  "@ (#> typein. c  1.5  87/01/07  Copyr  1986  Sun  Micro"; 
fendif  ' 

/********************************  ^*  ***********************/ 

finclude  <stdio.h> 

#include  <suritool/sunview.h> 
finclude  <suntool/canvas . h> 
finclude  <suntool/tty.h> 
finclude  <ctype.h> 


f  rame ; 
canvas; 
tty; 

*pw; 

static  Notify_client 

f define  STDIN_FD 
fdefine  STD0UT_FD 
fdefine  BUFSIZE 

main(argc,  argv) 
int  argc; 

char  **argv; 

{ 

static  Notify_value  read_input {)  ; 
int  tty_fd; 

frame  =  window_create (NULL,  FRAME, 

FRAME_ARGS,  argc,  argv, 

WIN_ERROR_MSG,  "Cannot  create  frame", 
FRAME_LABEL ,  " type in " , 

0); 


my_cl ient ; 

0 

1 

1000 


static  Frame 
static  Canvas 
static  Tty 
static  Pixwin 


tty  =  window_create (frame,  TTY, 

WIN_PERCENT_HEIGHT,  50, 

TTy_ARGV,  TTy_ARGV_D0_N0T_F0RK, 

0); 

tty_fd  =  (int) window_get (tty,  TTY_TTY_FD) ; 
dup2 (tty_f d,  STD0UT_FD) ; 
dup2 (tty_fd,  STDIN_FD) ; 


canvas  =  window_create (frame, 

0); 

pw  =  canvas  pixwin (canvas) ; 


CANVAS, 


/* 

*  Set  up  a  notify  proc  so  that  whenever  there  is  input  to  read  on 

*  stdin  (fd  0)  ,  we  are  called  to  read.  it. 

*  Notifier  needs  a  unique  handle:  give  it  the  address  of  tty. 

*/ 

my_Glient  =  (Not ify_cl ient )  &tty; 

notify_set__input__func  (my_client,  read__input,  STDIN_FD) ; 


printf ("Enter  first  coordinate : \nx?  "); 
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window_inain_loop  (frame)  ; 
exit  ( 0 ) ; 


*  This  section  implements  a  simple  application  which  writes  prompts  to 

*  stdin  and  reads  coordinates  from  stdout,  drawing  vectors  with  the 

*  supplied  coordinates .  It  uses  a  state  machine  to  keep  track  of  what 

*  number  to  read  next. 

*/ 

#define  GET_X_1  0 

#define  GET_Y_1  1 

#define  GET__X_2  2 

#define  GET_Y_2  3 

int  state  =  GET_X_1; 
int  xl,  yl,  x2,  y2; 


/*  ARGSUSED  */ 
static  Notify_value 
read_input (client,  in_fd) 
Notify_client  client; 
int  in  fd; 


/*  unused  since  this  must  be  from  ttysw  */ 
/*  unused  since  this  is  stdin  */ 


char  buf [BUFSIZE] ; 
char  *ptr,  *gets(); 

ptr  =  gets (buf) ;  /*  read  one  line  per  call  so  that  we 

don't  ever  block  */ 

/*  does  this  matter  any  more??  */ 

/*  handle  end  of  file  */ 
if  (ptr==NULL)  { 

/*  Note:  could  have  been  a  read  error  */ 
window_set (frame,  FRAME_NO_CONFIRM,  TRUE,  0); 
window_done (tty) ; 

}  else  { 

switch  (state)  { 
case  GET_X_1 : 

if  (sscanf(buf,  ”%d",  &xl)  !=  1)  { 

printf ("Illegal  value! \nx?  "); 
f flush (stdout) ; 

}  else  { 

printf  ("y?  ")  ; 
f flush (stdout) ; 
state++; 

} 

break; 

case  GET_Y_1: 

if  (sscanf(buf,  "%d",  &yl)  !=  1)  { 

printf ("Illegal  value! \ny?  "); 
f flush (stdout) ; 

}  else  { 

printf ("Enter  second  coordinate : \nx?  ") ; 

f flush (stdout) ; 

state++; 

} 

break; 

case  GET  X  2: 


w 

XT  microsystems 


Revision  A,  of  May  9,  1988 


440  SunView  1  Programmer’s  Guide 


if  (sscanf  (buf ,  ''%d" ,  &x2)  !=  1)  { 

printf ("Illegal  value !\nx?  "); 
f flush (stdout) ; 

}  else  { 

print f("y?  ")  ; 
f flush (stdout) ; 
state++; 


} 

break; 

case  GET_Y_2 : 

if  (sscanf(buf,  "%d”,  &y2)  !=  1)  { 

printf ("Illegal  value! \ny?  "); 
f flush (stdout) ; 

}  else  { 

printf ("Vector  from  (%d,  %d)  to  (%d,  %d)\n", 
xl ,  y  1 ,  x2 ,  y2 )  ; 

pw_vector (pw,  xl,  yl,  x2,  y2,  PIX_SET,  1); 
printf ("\nEnter  first  coordinate; \nx?  "); 
f flush (stdout) ; 
state  =  GET_X_1; 

} 

break; 

} 


} 

return (N0TIFY_D0NE)  ; 
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A.9.  Programs  that 
Manipulate  Color 


coloredit 


The  following  two  programs  work  with  color.  You  can  run  them  on  a  mono¬ 
chrome  workstation  to  no  iU-effect,  but  you  won’t  see  much  of  interest. 

The  techniques  employed  by  these  two  programs  are  explained  in  the  Color  sec¬ 
tion  of  Chapter  7,  Imaging  Facilities:  Pixwins. 

When  using  these  programs,  try  invoking  them  with  different  colors  using  the 
frame’s  command  line  arguments.  Also,  run  showcolor  (listed  in  the  pixwin 
chapter)  to  see  how  the  screen’s  colormap  changes  as  different  color  programs 
are  run  simultaneously. 

The  first  program,  coloredit,  puts  up  sliders  that  let  the  user  modify  its  colors. 
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^***************************************************************************/ 
#ifndef  lint 

static  char  sccsid[]  =  "0 (#) coloredit .c  1.4  86/09/15  Copyr  1986  Sun  Micro”; 
#endif 

/***************************************************************************/ 

tinclude  <suntool/sunview .h> 

#include  <suntool/panel .h> 

#include  <suntool/canvas . h> 

#define  MYFRAME  0 

#define  MYPANEL  1 

#define  MYCANVAS  2 

/*  colormap  sizes  for  the  three  windows.  Canvas  is  still  the  biggest  */ 


mycms  sizes [3] 

=  { 

2,  2, 

}; 

4 

♦define  MYCMS 

SIZE  4 

/*  color  arrays;  initialize  them  with  the  canvas  colors  */ 

unsigned  char 

red[MYCMS_SIZE]  =  {0,  0,  255,  255}; 

unsigned  char 

green[MYCMS_SIZE]  =  {0,  255,  0,  192}; 

unsigned  char 

blue[MYCMS_SIZE]  =  {255,  0,  0,  192}; 

static  void 

getcms  () ; 

static  void 

setcms  0 ; 

static  void 

cycle  ()  ; 

static  void 

edi terns  ()  ; 

static  void 

set_color  0  ; 

static  void 

change_value  () ; 

Panel_item 

text_item; 

Panel_item 

color_item; 

Panel_item 

red  item,  green_item,  blue_item; 

Pixwin 

*pixwins [3] ; 

Pixwin 

*pw; 

main (argc,  argv) 
int 
char 

{ 

Frame 

Panel 

Canvas 


argc; 

**argv; 

base_frame; 
panel ; 
canvas; 


Attr_avlist  sliderdef ault s; 

/*  the  cmsname  is  copied,  so  this  array  can  be  reused  */ 
char  cmsname [CMS_NAMESIZE] ; 

int  counter; 

int  xposition; 

char  buf[40]; 


base_frame  =  window__create  (NULL,  FRAME, 

FRAME  LABEL,  "coloredit". 
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FRAME_ARGS, 

0); 


argc,  argv. 


/*  set  up  the  panel  */ 

panel  =  window_create (base_frame,  PANEL, 

0)  ; 

/*  create  a  reusable  attribute  list  for  my  slider  attributes  */ 
sliderdefaults  =  attr_create_list ( 

PANEL_SHOW_I TEM ,  TRUE , 

PANEL_MIN_VALUE ,  0 , 

PANEL_MAX_VALUE ,  255, 

PANEL_SLIDER_WIDTH,  512, 

P ANEL_SHOW_RANGE ,  TRUE , 

PANEL_SHOW__VALUE,  TRUE, 

PANEL_NOTIFY_LEVEL,  PANEL_ALL, 

0); 


panel_create_it em (panel ,  PANEL_CYCLE , 

PANEL_LABEL_STR1NG,  "Edit  colormap:", 

PANEL_VALUE,  MYCANVAS, 

PANEL_CHOICE_STRINGS,  "Frame",  "Panel",  "Canvas",  0, 
PANEL_NOTIFY_PROC,  editcms, 

0); 


text_item  =  panel_create_item (panel ,  PANEL_TEXT, 

PANEL_VALUE_D I SPLAY_LENGTH , 
PANEL_VALUE_STORED_LENGTH , 
0); 


CMS_NAMESIZE, 
CMS  NAMESIZE, 


color_item  =  panel_create_item (panel,  PANEL_SLIDER, 

ATTR_LIST, 

PANEL_LABEL_STRING, 

P ANEL_N0T IF Y_PR0C , 

0); 


sliderdefaults, 
"color: " , 
set  color. 


red_item  =panel_create_item (panel,  PANEL_SLIDER, 

ATTR_LIST, 
PANEL_LABEL_STRI  NG, 
PANEL_NOT IFY_PROC, 
0); 


sliderdefaults , 
"  red:", 
change  value. 


green_item  =  panel_create_item (panel,  PANEL_SLIDER, 

ATTR_LIST,  sliderdefaults, 

PANEL_LABEL_STRING,  " green : " , 
PANEL_NOTIFY_PROC,  change_value, 

0); 

blue_item  =  panel_create_item (panel,  PANEL_SLIDER, 

ATTR_LIST,  sliderdefaults, 

PANEL_LABEL_STRING,  "  blue:", 
PANEL_NOTIFY_PROC,  change_value, 

0>; 

panel_create_item (panel,  PANEL_BUTTON , 

PANEL  LABEL  IMAGE, 
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panel_button_image (panel,  "Cycle  colormap" ,  12,  NULL), 
PANEL_NOTIFY_PROC,  cycle, 

0); 

window_fit (panel)  ;  ' 

window_fit_width (base_f rame) ; 

/*  free  the  slider  attribute  list  */ 
free (sliderdefaults)  ; 

/*  set  up  the  canvas  */ 

canvas  =  window_create (base_frame,  CANVAS,  0); 

/*  get  pixwins  */ 

pixwins [MYFRAME]  =  (Pixwin  *)  window_get (base_frame,  WIN_PIXWIN) ; 
pixwins [MYPANEL]  =  (Pixwin  *)  window_get (panel,  WIN_PIXWIN) ; 
pw  =  pixwins [MYCANVAS]  =  (Pixwin  *)  canvas_pixwin (canvas) ; 

/*  set  up  the  canvas'  colormap  */ 

sprint  f  (cmsname,  "coloredit%D" ,  getpidO); 

pw_setcmsname (pw,  cmsname); 

pw_put colormap (pw,  0,  mycms_sizes [MYCANVAS] ,  red,  green,  blue); 

/*  draw  in  the  canvas  */ 

/*  don't  draw  color  0  —  it  is  the  background  */ 

for  (counter  =  1;  counter  <  mycms_sizes [MYCANVAS] ;  counter++)  [ 
xposition  =  counter  *  100; 
pw_rop(pw,  xposition,  50,  50,  50, 

PIX_SRC  I  PIX_C0L0R (counter)  ,  NULL,  0,  0); 
sprintf(buf,  "%d",  counter); 

pw_text  (pw,  xposition  +  5,  70,  PIX_SRC  PIX_DST,  0,  buf )  ; 

} 

pw_text(pw,  100,  150, 

PIX_SRC  I  PIX_C0L0R (mycms_sizes [MYCANVAS]  -1),  0, 

"This  is  written  in  the  foreground  color"); 

/*  initialize  to  edit  the  first  canvas  color  */ 
edit cms (NULL,  MYCANVAS,  NULL) ; 

window_main_loop (base_frame)  ; 
exit (0) ; 


static  int  cur_cms  =  -1; 

/*  ARGSUSED  */ 
static  void 

editcms (item,  value,  event) 

Panel_item  item; 

un signed  int  value; 

Event  * event; 


int  planes; 

struct  colormapseg  cms; 

char  cmsname [CMS_NAMESIZE] ; 

if  (value  “  cur_cms) 
return ; 
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cur_cms  =  value; 

/*  get  the  new  cmsname  */ 

pw_getcmsname (pixwins [cur_cms] ,  cmsname) ; 
panel_set_value (text_item,  cmsname) ; 

pw  =  pixwins [cur_cms]  ; 

/*  get  the  new  colormap  */ 

/* 

*  first  have  to  get  its  size  there  is  NO  DOCUMENTED  procedure  to  do 

*  this. 

*/ 

pw_getcmsdata (pw,  &cms,  Splanes); 

pw_get colormap (pw,  0,  cms . cms_size,  red,  green,  blue) ; 

panel_set (color_item, 

PANEL_VALUE,  0, 

PANEL_MAX_VALUE,  cms.cms_size  -  1, 

0); 

/*  call  the  proc  to  set  the  colors  */ 
set_color (NULL,  0,  NULL) ; 


int  cur_color; 

/*  ARGSUSED  */ 
static  void 

set_color (item,  color,  event) 
Panel_item  item; 

unsigned  int  color; 

struct  inputevent  *event; 


panel_set_value (red_item,  red[color] ) ; 
panel_set_value (green_item,  green [ color] ) ; 
panel_set_value (blue_item,  blue [color] ) ; 
cur_color  =  (unsigned  char)  color; 


/*  ARGSUSED  */ 
static  void 

change_value (item,  value,  event) 

Panel_item  item; 

int  value; 

struct  inputevent  *ev6nt; 

{ 

if  (item  ==  red_item) 

red [cur_color]  =  (unsigned  char)  value; 
else  if  (item  ==  green_item) 

green [cur_color]  =  (unsigned  char)  value; 

else 

blue [cur_color]  =  (unsigned  char)  value; 

/* 

*  pw_put colormap  expects  arrays  of  colors,  but  this  only  sets  one 

*  color  ^ 

*/ 

pw_putcolormap (pw,  cur_color,  1, 

&red  [cur_color]  ,  &green  [cur__color]  ,  Sblue  [cur_color]  )  ; 
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animatecolor 


This  program  demonstrates  smooth  animation  via  the  technique  of  software 
double-buffering.  Two  colormaps  for  the  canvas  are  set  up  so  that  while  one  is 
being  written  two,  the  other  is  being  displayed.  This  allows  smoother  animation. 

The  routines  that  set  up  the  colormaps  and  swap  them,  doublebuf  f_init  ( ) 
and  doublebuf  f_swap  ( ) ,  are  general  enough  to  be  used  in  other  programs 
that  alternate  two  colormaps.  You  need  only  set  up  a  similar  color  stuff 
structure  to  use  these  routines  in  another  program. 

The  logic  involved  in  creating  the  colormaps  is  complex.  The  colormaps  created 
for  animatecolor  are  given  in  the  table  Sample  Colormap  to  Isolate  Planes  in  the 
pixwin  chapter. 
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/*************************************** 

#ifndef  lint 

static  char  sccsid[]  =  "@ {#) animatecolor .c  1.4  88/03/09  Copyr  1986  Sun  Micro'; 
#endif 

it  it* -k-k******  ***************************************************  / 

#include  <suntool/sunview.h> 
finclude  <suntool/canvas .h> 


/***************************************************************/ 
/*  You  set  MYCOLORS  &  MYNBITS  according  to  how  many  colors  */ 

/*  you  are  using;  rest  is  just  boilerplate,  mote  or  less;  */ 

/*  it  you  define  your  colors.  */ 

^it**************************************************************  / 
/* 

*  define  the  colors  I  want  in  the  canvas;  max  16,  must  be  a 

*  power  of  2 
*/ 

#define  MYCOLORS  4 

/* 

*  define  the  number  of  bits  my  colors  take  up  —  MYCOLORS  log  2; 

*  maximum  for  animation  to  be  possible  is  half  screen's  bits  per 

*  pixel  —  4  bits  on  current  Sun  color  displays. 

*  / 

#define  MYNBITS  2 

/* 

*  to  "hide"  one  set  of  planes  while  displaying  another  takes  a 

*  large  cms  —  the  square  of  the  number  of  colors 


*/ 

#define  MYCMS  SIZE 


(MYCOLORS  *  MYCOLORS) 


/* 

*  when  you  write  out  a  color  pixel,  you  must  write  the  color  in 

*  the  appropriate  planes.  This  macro  writes  it  in  both  sets 
*/ 

#define  usecolor(i)  (  (i)  I  ( (i)  colorstuff .  colorbits)  ) 


struct  colorstuff  { 

/*  desired  colors  */ 

unsigned  char  redcolors [MYCOLORS] ; 

unsigned  char  greencolors [MYCOLORS] ; 

unsigned  char  bluecolors [MYCOLORS] ; 

/*  number  of  bits  the  desired  colors  take  up  */ 

.  int  colorbits; 

/*  colormap  segment  size  */ 
int  cms_size; 

/*  2  colormaps  to  support  it  */  v 

unsigned  char  red[2]  [MYCMS__SIZE]  ; 

unsigned  char  green [2] [MYCMS_SIZE] ; 

unsigned  char  blue[2] [MYCMS_SIZE] ; 

/*  2  masks  to  support  it  */ 
int  enable_0_mask; 

int  enable_l_mask; 

/*  current  colormap  —  0  or  1  */ 
int  cur_buff; 

/*  plane  mask  to  control  which  planes  are  written  to  */ 
int  pi ane_ma  sk ; 
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{0,  0,  255,  255}, 


struct  colorstuff  colorstuff  =  { 

/*  desired  red  colors  */ 

/*  desired  green  colors  */ 

{0,  255,  0,  192}, 

/*  desired  blue  colors  */ 

{255,  0,  0,  192}, 

/*  number  of  planes  these  colors  take  up  */ 

MYNBITS, 

/*  colormap  segment  size  */ 

MYCMS_SIZE, 

/*  rest  filled  in  later  */ 

}; 

static  void  resize_proc () ; 

/*  stuff  needed  to  do  random  numbers  */ 

extern  void  srandom(); 

extern  int  getpid(); 

extern  long  random (); 

extern  char  *sprintf  ()  ; 

static  Notify_value  my_frame_interposer () ; 
static  Notify_value  my_draw () ; 

static  Pixwin  *pw; 

static  int  times_drawn; 

static  int  Xmax,  Ymax; 


main(argc,  argv) 
int 
char 

{ 

Frame 

Canvas 


argc  ; 
**argv; 

base_frame; 

canvas; 


base_frame  =  window_create (NOLL,  FRAME, 

FRAME_LABEL,  "animatecolor" , 
FRAME_ARGS,  argc,  argv, 

0)  ; 

canvas  =  window_create  (base__frame,  CANVAS, 

CANVAS_RETAINED,  TRUE, 
CANVAS_RESIZE_PROC,  resize_proc, 
0>; 

pw  =  (Pixwin  *)  canvas_pixwin (canvas) ; 

/*  set  up  the  canvas'  colormap  */ 
doublebuf f_init (&colorstuff ) ; 

/*  run  the  drawing  routine  as  often  as  possible  */ 

(void)  notify_set_itimer_func (base_frame,  my_draw, 

ITIMER_REAL, 
&NOTIFY_POLLING_ITIMER, 
((struct  itimerval  *)  0)); 

/*  initialize  the  random  function  */ 
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srandom (getpid  () ) ; 
window_main_loop (base_f  rame) ; 
exit (0) ; 


/*  ARGSUSED  */ 

static  Notify_value 

my_draw (client,  itimer_type) 

Notify_client  client; 
int  itimer_type; 

{ 

/* 

*  draw  the  squares,  then  swap  the  colormap  to  animate  them 
*/ 

♦define  SQUARE SIZE  50 

♦define  MAX_VEL  (SQUARESIZE  /  5) 

/*  number  of  squares  to  animate  */ 

♦define  NUMBER  (MYCOLORS  -  1) 


static  int 
static  int 
static  int 
int 


posx [NUMBER] ,  posy [NUMBER] ; 
vx [NUMBER] ,  vy [NUMBER] ; 
prevposx [NUMBER] ,  prevposy [NUMBER] ; 
i; 


/*  set  the  plane  mask  to  be  that  which  we  are  not  viewing  */ 
pw_j)utattributes  (pw,  (colorstuff  •cur_buff  ==  1)  ? 

& (colorstuff .enable_l_mask} :  & (colorstuff .enable_0_mask) ) ; 


/*  write  to  invisible  planes  */ 
for  (i  =0;  i  <  NUMBER;  i++)  { 
if  ( ! times_drawn)  { 

/*  first  time  drawing  */ 

posx[i]  =  (i  +  1)  *  100; 
posy[i]  =  50; 

vx[i]  =  r(-MAX_VEL,  MAX_VEL) ; 
vy[i]  =  r(-MAX_VEL,  MAX_VEL) ; 

} 

if  (abs(vx[i])  >  MAX_VEL>  { 

printf ("Weird  value  (%d)  for  vx[%d] \n”,  vx[i] ,  i) ; 
vx[i]  =  r(-MAX_VEL,  MAX_VEL) ; 

} 

posx[i]  ==  posx[i]  +  vx[i];  ^ 

if  (posx[i]  <  0)  { 

/*  Bounce  off  the  left  wall  */ 
posx[i]  =0; 
vx[i]  =  -vx[i]; 

}  else  if  (posx[i]  >  Xmax  -  SQUARESIZE)  { 

/*  Bounce  off  the  right  wall  */ 

vx[i]  =  -vx[i]; 

posx[i]  =  posx[i]  +  vx[i]; 

} 

posy[i]  =  posy[i]  +  vy[i]; 
if  (posy[i]  >■  Ymax  ~  SQUARESIZE)  { 

/*  Bounce  off  the  top  */ 
posy[i]  =  Ymax  —  SQUARESIZE; 
vy[i]  =  -vy[i]; 

}  else  if  (posy[i]  <  0)  { 
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} 

/* 


/*  Bounce  off  the  bottom  */ 
posy[i]  =  0; 
vy[i]  =  -vy[i]; 

} 

/*  draw  the  square  you  can't  see  */ 

pw_rop(pw,  posx[i],  posy[i],  SQUARESIZE,  SQUARESIZE, 

PIX_SRC  I  PIX_COLOR(usecolor (i  +1)),  NULL,  0,  0) ; 


*  swap  the  colormaps,  and  hey  presto!  should  appear  smoothly 
*/ 

doublebuff_swap{&colorstuff) ; 
times_drawn++; 

/*  set  the  plane  mask  to  be  that  which  we  are  not  viewing  */ 
pw_j>utattributes  (pw,  (colorstuf  f .  cur_buff  ==  1)  ? 

& (colorstuff .enable_l_mask) ;  & (colorstuf f. enable  0  mask)); 

/*  erase  now  invisible  planes  */ 
for  (i  =  0;  i  <  NUMBER;  i++)  { 

if  (times__drawn  >  1)  { 

/*  squares  have  been  drawn  before  */ 

/*  erase  in  the  one  you  can't  see  */ 
pw_rop (pw ,  prevposx [ i ] ,  prevposy [ i ] , 

SQUARESIZE^  SQUARESIZE,  PIX_CLR,  NULL,  0,  0) ; 

} 

/*  remember  so  can  erase  later  */ 
prevposx[i]  =  posx[i]; 
prevposy [i]  =posy[i]; 


/* 

*  set  the  plane  mask  to  be  that  which  we  are  viewing,  in 

*  case  screen  has  to  be  repaired  between  now  an  when  we  are 

*  called  again. 

*/ 

pw_putattributes (pw,  (colorstuff .cur_buff  ==  1)  ? 

& (colorstuff .enable_0_mask)  :  &  (colorstuff . enable  1  mask) ) ; 


/*  random  number  calculator  */ 
int 

r(minr,  maxr) 

int  minr,  maxr; 

{ 


int 


i; 


i  =  random  0  %  (maxr  -  minr  +  1); 
if  (i  <  0) 

return  (i  +  maxr  +1); 

else 

return  (i  +  minr) ; 
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/*  ARGSUNUSED  */ 
static  void 

resize_proc (canvas ,  width,  height) 

{ 

times_drawn  =  0; 

/*  remember,  pixels  start  at  0,  not,  1,  in  the  pixwin  */ 

Xmax  =  width  -  1; 

Ymax  =  height  -  1; 

} 

/* 

*  Do  double  buffering  by  changing  the  write  enable  planes  and 

*  the  color  maps.  The  application  draws  into  a  buffer  which  is 

*  not  visible  and  when  the  buffers  are  swapped  the  invisible  one 

*  become  visible  and  the  other  become  invis. 

* 

*  Start  out  drawing  into  buffer  1  which  is  the  low-order  buffer; 

*  ie .  the  low— order  planes.  Things  would  not  work  if  this  is  not 

*  done  because  the  devices  start  out  be  drawing  with  color  1 

*  which  will  only  hit  the  low-order  planes. 

•k 

*  Init  double  buffering:  Allocate  color  maps  for  both  buffers.  Fill 

*  in  color  maps. 

*/ 

doublebuff_init (colorstuff ) 

struct  colorstuff  *colorstuff; 

{ 

/* 

*  user  has  defined  desired  colors.  Set  them  up  in  the  two 

*  colormap  segments 


*/ 

int 

index_l ; 

int 

index_2 ; 

int 

i; 

char 

cmsname [CMS  NAMESI ZE ] ; 

/*  name  colormap  something  unique  */ 
sprintf  (cmsname,  "animatecolor%D" ,  getpidO); 
pw_setcmsname (pw,  cmsname); 

/* 

*  for  each  index  in  each  color  table,  figure  out  how  it  maps 

*  into  the  original  color  table. 

*/ 

for  (i  =0;  i  <  colorstuff->cms_size;  i++)  { 

/* 

*  first  colormap  will  show  color  X  whenever  low  order 

*  bits  of  color  index  are  X 
*/ 

index_l  =  i  &  ( (1  «  colorstuf f->colorbits)  -  1); 

/* 

*  second  colormap  will  show  color  X  whenever  high  order 

*  bits  of  color  index  are  X 
*/ 

index  2  =  i  »  colorstuff->colorbits; 
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colorstuff->red[0]  [i]  =  colorst.uff-'>redcolors  [index_l] ; 
color stuf f->green [0] [i]  =  colorstuff->greencolors[index_l]; 
colorstuff— >blue  [0]  [i]  =  colorst.uff—>blueGolors  [index  1]; 

colorstuff->red [1  ]  [i ]  =  colorstuff->redcolors  [index__2] ; 
colorstuff->green  [1]  [i]  =  color.stuff->greencolors  [index_2  ]  ; 
colorstuff->blue [1] [i]  =  colorstuff->bluecolors [index_2 ] ; 

} 

colorstuff->enable_l_mask  =  ( (1  «  colorstuf f->colorbits)  -  1) 
«  colorstuf f->colorbits; 

colorstuff->enable_0_mask  =  ( (1  «  colorstuff->colorbits}  -  1) ; 
/* 

*  doublebuff_swap  sets  up  the  colormap.  We  want  the  drawing 

*  to  start  off  drawing  into  the  1st  buffer,  so  set  the 

*  current  buffer  to  1  so  that  when  doublebuff_swap  is  called 

*  it  will  set  up  the  first  ([0]  )  colormap. 

*/ 

colorstuf f->cur_buff  ==  1; 
doublebuff_swap {colorstuff )  ; 

} 


/* 

*  Routine  to  swap  buffers  by  loading  a  color  map  that  will  show 

*  the  contents  of  the  buffer  that  was  not  visible.  Also,  set  the 

*  write  enable  plane  so  that  future  writes  will  only  effect  the 

*  planes  which  are  not  visible. 

*/ 

doublebuff_swap (colorstuff) 

struct  colorstuff  *colorstuff; 

{ 

if  (colorstuff->cur_buff  ==  0)  { 

/*  display  first  buffer  while  writing  to  2nd  */ 

/* 

*  Careful!  pw_putcolormap ()  wants  an  array  or  pointer 

*  passed,  but  the  colormap  arrays  are  2-d 
*/ 

pw_jputcolormap  (pw,  0,  colorstuff->cms_size, 
colorstuff->red[0]  , 
color stuf f->green [0]  , 
color stuf f ->blue [0] ) ; 

/*  set  plane  mask  to  write  to  second  buffer  */ 
color stuf f->plane_mask  =  colorstuf f->enable_l_mask; 
colorstuff->cur_buff  =  1; 

}  else  { 

/*  display  second  buffer  while  writing  to  first  */ 
pw_jput colormap  (pw,  0,  colorstuff->cms_size, 
color stuf f ->red [1 ]  , 
colorstuff->green [1]  , 
colorstuf f->blue [ 1 ] ) ; 


/*  set  plane  mask  to  write  to  first  buffer  */ 
colorstuff->plane_mask  =  colorstuff->enable_0_mask; 
color St uff->cur  buff  =  0; 
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A.IO.  Two  gfx 

subwindow-based 
programs  converted 
to  use  SunView 


The  following  two  programs  are  the  Sim  demo  programs  bouncedemo  and 
spheresdemo  converted  from  using  gf  xsw_init  ( )  to  canvases  in  SunView. 

The  code  for  the  SunWindows-based  programs  is  in 

/usr/ share/ src/ sun/ suntool  so  you  can  contrast  that  code  with  the 

SunView  versions  printed  here. 

Techniques  used  to  convert  programs  such  as  these  to  SunView  1  are  described 
in  Appendix  C,  Converting  SunWindows  Programs  to  SunView. 


bounce  The  first  program  is  bouncedemo  converted  to  draw  in  a  canvas  and  to  call 

notify_dispatch  ()  periodically.  Like  the  original  it  restarts 

drawing  after  any  damage  (if  not  retained)  or  resizing. 
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#ifndef  lint 

static  char  sccsid[]  =  "@  {#) bounce . c  1.5  88/02/26  Copyr  1986  Sun  Micro"; 
fendif 

/* 

*  Overview:  Bouncing  ball  demo  in  window. 

*  Converted  to  use  SunView  by  simulating  the  gfxsubwindow  structure. 

*/ 

/*  this  replaces  all  includes  */ 
tinclude  <suntool/sunview.h> 
tinclude  <suntool/canvas .h> 

/*  straight  from  the  Canvas  chapter  */ 
static  void  repaint_proc () ; 

static  void  resize_proc (} ; 

/*  straight  from  the  Notifier  chapter  */ 
static  Notify_value  my_notice_destroy () ; 
extern  Notify_error  notify  dispatch (); 


static  int 


my_done ; 


/*  define  my  own  gfxsubwindow  struct  */ 
struct  gfxsubwindow  { 

int  gfx_flags; 

#define  GFX_RESTART  0x01 

#define  GFX_DAMAGED  0x02 

int  gfx_reps; 

struct  pixwin  *gfx__pixwin; 
struct  rect  gfx_rect; 

}  mygfx; 

struct  gfxsubwindow  *gfx  =  Smygfx; 
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main  (argc,  argv) 
int 


argc; 

**argv; 


short  X,  y,  vx,  vy,  z,  ylastcount,  ylast; 

short  Xmax,  Ymaxr'  size; 

/*  WIN_RECT  attribute  returns  a  pointer  */ 

Rect  *rect; 

/*  have  to  handle  this  arg  that  gfxsw_init  used  to  process  */ 
int  retained; 


*  replace  this  call  if  (gfx  ==  (struct  gfxsubwindow  *) 0)  exit(l); 

*  with  . . . 


Frame 

Canvas 

Pixwin 


frame; 

canvas; 


/*  this  arg  was  also  dealt  with  by  gfxsw_init  */ 
gfx->gfx_reps  =  200000; 

frame  =  window_create (NULL,  FRAME, 

FRAME_LABEL,  "bounce" , 

FRAME_ARGC_PTR_ARGV,  Sargc,  argv, 

WIN_ERROR_MSG,  "Can't  create  frame”, 

0); 

for  ( — argc,  ++argv;  *argv;  argv++>  { 

/* 

*  handle  the  arguments  that  gfxsw_init  (0,  argv)  used  to  do 

*  for  you 
*/ 

if  (strcmp  (*argv,  ”-r”)  ==  0) 
retained  =1; 

if  (strcmp (*argv,  ”-n")  ==  0) 
if  (argc  >  1)  { 

(void)  sscanf (* (++argv) ,  ”%hD",  &gfx->gfx_reps) ; 
argc++; 

} 


canvas  =  window_create (frame,  CANVAS, 

CANVAS_RETAINED,  retained, 
CANVAS_RESIZE_PROC,  resize_j>roc, 
CANVAS_FAST_MONO,  TRUE, 

WIN_ERROR_MSG,  "Can't  create  canvas", 
0)  ; 

/*  only  need  to  define  a  repaint  proc  if  not  retained  */ 
if  ( ! retained)  { 

window_set (canvas, 

CANVAS_REPAINT_PROC,  repaint_proc , 

0); 


pw  =  canvas_j5ixwin  (canvas) 
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gfx->gfx_pixwin  =  canvas_pixwin (canvas) ; 

/*  Interpose  proc  so  I  know  that  the  tool  is  going  away.  */ 
(void)  notify_interpose_destroy_func (frame,  my_notice_destroy) ; 

/* 

*  Note:  instead  of  window_main_loop,  just  show  the  frame.  The 

*  drawing  loop  is  in  control,  not  the  notifier. 

*/ 

window_set (frame,  WIN_SHOW,  TRUE,  0); 
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Restart : 


rect  =  (Rect  *)  window_get (canvas,  WIN_RECT) ; 

Xmax  =  rect_right (rect) ; 

Ymax  =  rect_bottoin  (rect)  ; 
if  (Xmax  <  Ymax) 

size  =  Xmax  /  29  +  1; 

else 

size  =  Ymax  /  29  +  1; 

/* 

*  the  following  were  always  0  in  a  gfx  subwindow  (bouncedemo 

*  is  confused  on  this  point 
*/ 

X  =  0; 

y  =  0; 

vx  =  4; 
vy  =  0; 
ylast  =0; 
ylastcount  =  0; 

pw_writebackground(pw,  0,  0,  rect->r_width,  rGct->r_height , 

PIX_SRC) ; 

/* 

*  Call  notify_dispatch 0  to  dispatch  events  to  the  frame 

*  regularly.  This  will  call  my  resize  and  repaint  procs  and 

*  interposed  notify_destroy_func  if  necessary.  The  latter  will 

*  set  my_done  to  TRUE  if  it's  time  to  finish. 

*/ 

while  (gfx->gfx_reps)  { 

(void)  notify_dispatch 0 ; 
if  (my_done) 

break ; 

/* 

*  this  program  is  not  concerned  with  damage,  because  either 

*  the  canvas  repairs  the  damage  (if  retained)  or  it  just 

*  restarts,  which  is  handled  by  GFX_RESTART 
*/ 

/* 

*  if  (gfx->gfx_flags&GFX_DAMAGED)  gfxsw_handlesigwinch (gfx) ; 
*/ 

if  (gfx->gfx_flags  &  GFX_RESTART)  { 

gfx->gfx_flags  &=  -GFX_RESTART; 
goto  Restart; 

} 

if  (y  ==  ylast)  { 

if  (ylastcount ++  >  5) 
goto  Reset; 

}  else  { 

ylast  =  y; 
ylastcount  =0; 


pw_writebackground (pw,  x,  y,  size,  size, 
PIX_NOT (PIX_DST) ) ; 

X  =  X  +  vx; 

if  (x  >  (Xmax  ~  size) )  { 

/* 

*  Bounce  off  the  right  edge 
*/ 

X  =  2  *  (Xmax  -  size)  -  x; 
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X  =  0; 

y  =  0; 
vx  =  4; 
vy  =  0; 
ylast  =0; 
ylastcount  =  0; 

} 

} 
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static  void 

repaint_proc (  /*  Ignore  args  */  } 

/*  if  repainting  is  required,  just  restart  */ 
gfx->gfx_flags  |=  GFX_RESTART; 

} 

static  void 

resize_proc(  /*  Ignore  args  */  ) 

{ 

gfx->gfx_flags  |=  GFX_RESTART; 

} 

/*  this  is  straight  from  the  Notifier  chapter  */ 
static  Notify_value 

my_notice_destroy (frame,  status) 

Frame  frame; 

Destroy_status  status; 

{ 

if  (status  !==  DESTROY_CHECKING)  { 

/*  set  my  flag  so  that  I  terminate  my  loop  soon  */ 
my_done  =  1; 

/*  Stop  the  notifier  if  blocked  on  read  or  select  */ 
(void)  notify_stop 0 ; 

} 

/*  Let  frame  get  destroy  event  */ 

return  (not ify_next_destroy_func (frame,  status)); 

} 
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spheres  This  is  an  example  of  a  program  that  has  been  converted  to  use 

window_main_loop  ( ) .  It  displays  a  fixed-sized  image  in  a  canvas  that  has 
scroUbars.  It  continues  drawing  its  image  when  its  window  is  damaged  or 
resized.  However,  it  stops  drawing  when  it  is  iconic. 

You  will  have  to  create  your  own  icon  for  this  called  sphere  s  .  icon. 
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#ifndef  lint 

static  char  sccsid[]  =  "@  (#} spheres .c  1.4  88/02/05  Copyr  1986  Sun  Micro"; 
#endif 
/* 

*  spheres  —  draw  a  bunch  of  shaded  spheres  Algorithm  was  done 

*  by  Tom  Duff,  Lucasfilm  Ltd.,  1982 

*  Revised  to  use  SunView  canvas  instead  of  gfxsw. 


tinclude  <suntool/sunview.h> 
#include  <suntool/canvas.h> 
#include  <suntool/ scrollbar .h> 
#include  <sunwindow/cms  rainbow. h> 


static  Notify_value  my_frame_interposer () ; 
static  Notify_value  my_animation () ; 
static  void  sphere  (); 

static  void  demoflushbuf () ; 


#define  ITIMER  NULL 


(  (struct  itimerval  *)  0) 


*  (NX,  NY,  NZ)  is  the  light  source  vector  —  length  should  be 

*  100 
*/ 

#define  NX  48 
tdefine  NY  -36 
fdefine  NZ  80 

tdefine  BUF_BITWIDTH  16 

static  struct  pixrect  *mpr; 
static  int  width; 

static  int  height; 

static  int  counter; 

static  Frame  frame; 

static  Canvas  canvas; 

static  int  cmssize; 

static  Pixwin  *pw; 

static  short  spheres_image [256]  =  { 

#include  " spheres . icon" 

}; 

mpr  static (spheres_pixrect,  64,  64,  1,  spheres_image) ; 


main(argc,  argv) 

int  argc; 

char  **argv; 

{ 

char  **args; 

int  usefullgray  =  0; 


icon  =  icon_create (ICON_IMAGE,  &spheres_pixrect ,  0) ; 
frame  =  window_create (NULL,  FRAME, 

FRAME  LABEL,  "spheres". 
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FRAME_ICON ,  icon , 

FRAME_ARGC_PTR_ARGV,  Sargc,  argv, 

0); 

canvas  =  window_create (frame,  CANVAS, 

CANVAS_AUTO_EXPAND,  0, 

CANVAS_AUTO_SHRINK,  0, 

CANVAS_AUTO_CLEAR ,  0 , 

/* 

*  Set  SCROLL_LINE_HEIGHT  to  1  so  that  clicking  LEFT  or  RIGHT 

*  in  the  scroll  buttons  scrolls  the  canvas  by  one  pixel. 

*/ 

WIN_VERTICAL_SCROLLBAR,  scrollbar_create (SCROLL_LINE_HEIGHT,  1, 

0), 

WIN_HORIZONTAL_SCROLLBAR,  scrollbar_create (SCROLL_LINE_HEIGHT,  1, 

0), 

0); 

for  (args  =  argv;  *args;  args++)  { 
if  (strcmp (*args,  "-g”)  ==  0) 
usefullgray  =1; 

} 

/*  Interpose  in  front  of  the  frame's  client  event  handler  */ 

(void)  notify_interpose_event_func (frame,  my_frame_interposer, 

NOTIFY_SAFE) ; 

(void)  notify_set_itimer_func (frame,  my_animation, 

ITIMER_REAL,  &NOTIFY_POLLING_ITIMER,  ITIMER_NULL) ; 

width  =  (int)  window_get (canvas ,  CANVAS_WIDTH) ; 
height  =  (int)  window_get (canvas,  CANVAS_HEIGHT) ; 
pw  =  canvas_pixwin (canvas) ; 

cmssize  =  (usefullgray)  ?  setupfullgraycolormap (pw)  : 
setuprainbowcolormap (pw) ; 

mpr  =  mem_create (BUF_BITWIDTH,  height,  pw->pw_pixrect->pr_depth) ; 
window_main_loop (frame) ; 
exit ( 0 ) ; 


static 

static 

static 

static 

static 

static 

static 

static 


radius; 

xO; 

yO; 

color; 

x; 

y; 

maxy; 
mark; 
xbuf  ; 


/*  X  center  */ 
/*  y  center  */ 


/*  ARGSUSED  */ 

static  Notify_value 

my_animation (client ,  itimer_type) 

Notify_client  client; 
int  itimer_type; 

{ 

register  i; 

if  (x  >=  radius)  { 

radius  =  r(0,  min (width  /  2,  height  /  2)); 
xO  =  r(0,  width); 
yO  =  r(0,  height); 
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color  =  r(0,  cmssize  +  counter++)  %  cmssize; 

X  =  -radius; 
xbuf  =  0; 

/* 

*  Don't  use  background  colored  sphere. 

*/ 

if  (color  ==  0) 
color++; 

/* 

*  Don't  use  tiny  sphere. 

*/ 

if  (radius  <  8) 
radius  =  8; 

} 

for  (i  =  0;  i  <  5;  i++)  { 
xbuf++; 

maxy  =  sqroot (radius  *  radius  -  x  *  x) ; 
pw_vector (pw,  xO  +  x,  yO  -  maxy,  xO  +  x,  yO  +  maxy, 
PIX_CLR,  0); 

for- (y  =  -maxy;  y  <=  maxy;  y++)  { 

mark  =  r(0,  radius  *  100)  <=  NX  *  x  +  NY  *  y 

+  NZ  *  sqroot (radius  *  radius  -x*x-y*y); 
if  (mark) 

pr_put (mpr,  xbuf,  y  +  yO,  color); 

} 

if  (xbuf  ==  (mpr->pr_width  -  1))  { 

demoflushbuf (mpr,  PIX_SRC  |  PIX_DST, 

X  +  xO  -  mpr->pr_width,  pw) ; 

xbuf  =  0; 

X++; 

return  (NOTIFY_DONE) ; 

} 

X++; 

} 

if  (x  >=  radius) 

demoflushbuf (mpr,  PIX_SRC  |  PIX_DST,  x  +  xO  -  (xbuf  +  2), 
pw)  ; 

return  (NOTIFY_DONE) ; 


static  void 

demoflushbuf (mpr,  op,  x,  pixwin) 
struct  pixrect  *mpr; 
int  op; 

int  x; 

struct  pixwin  *pixwin;  v 

{ 

register  u_char  *sptr,  *end; 

sptr  =  mprd8_addr (mpr_d  (mpr) ,  0,  0,  mpr->pr_depth) ; 
end  =  mprd8_addr  (mpr_d  (mpr)  ,  itpr->pr_width  -  1, 

mpr->pr_height  -  1,  n:pr->pr_depth)  ; 

/* 

*  Flush  the  mpr  to  the  pixwin. 

*/ 

pw_write (pixwin,  x,  0,  mpr->pr_width,  mpr->pr_height ,  op. 
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mpr,  0,  0); 

/* 

*  Clear  mpr  with  O's 
*/ 

while  (sptr  <=  end) 

*sptr++  =  0; 

/*  Let  user  interact  with  tool  */ 
notify_dispatch  0 ; 


static  int 

setuprainbowcolormap (pw) 

Pixwin  *pw; 

{ 

register  u_char  red [CMS_RAINBOWSIZE] ; 
register  u_char  green [CMS_RAINBOWSIZE] ; 
register  u  char  blue [CMS_RAINBOWSIZE] ; 


*  Initialize  to  rainbow  cms. 

*/ 

pw_setcmsname (pw,  CMS_RAINBOW) ; 
cms_ra inbow set up (red,  green,  blue) ; 

pw_j)utcolormap (pw,  0,  CMS_RAINBOWSIZE,  red,  green,  blue) ; 
return  (CMS  RAINBOWSIZE) ; 


static  int 

setupfullgraycolormap (pw) 

Pixwin  *pw; 

{ 

#define  CMS_FULLGRAYSIZE  256 

tdefine  CMS_FULLGRAY  "fullgray" 

register  u_char  red [CMS_FULLGRAYSIZE] ; 
register  u_char  green [CMS_FULLGRAYSIZE] ; 
register  u_char  blue [CMS_FDLLGRAYSIZE] ; 
register  i; 


*  Initialize  to  rainbow  cms. 

*/ 

pw_setcmsname (pw,  CMS_FULLGRAY) ; 
for  (i  =  0;  i  <  CMS_FULLGRAYSIZE;  i++)  { 
red[i]  =  green [i]  =  blue[i]  =  i; 

} 

pw_putcolormap (pw,  0,  CMS_FULLGRAYSIZE,  red,  green,  blue); 
return  (CMS  FULLGRAYSIZE) ; 


static  Notify_value 

my_frame_interposer (frame,  event,  arg,  type) 
Frame  frame; 

Event  * event; 

Notify_arg  arg; 

Notify_event_type  type; 
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int  closed_initial,  closed_current ; 

Notify_value  value; 

/*  Determine  initial  state  of  frame  */ 

closed_initial  =  (int)  window_get (frame,  FRAME_CLOSED) ; 

/*  Let  frame  operate  on  the  event  */ 

value  =  not if y_next_event_func (frame,  event,  arg,  type); 

/*  Determine  current  state  of  frame  */ 

closed_current  =  (int)  window_get (frame,  FRAME_CLOSED) ; 

/*  Change  animation  if  states  differ  */ 
if  {closed_initial  !=  closed_current )  ( 
if  (closed_current )  { 

/*  Turn  off  animation  because  closed  */ 

(void)  notify_set_itimer_func (frame,  my_animation, 

ITIMER_REAL,  ITIMER_NULL,  ITIMER_NULL) ; 

}  else  { 

/*  Turn  on  animation  because  opened  */ 

(void)  notify_set_itimer_func (frame,  my_animation, 

ITIMER_REAL,  &NOTIFY_POLLING_ITIMER, 
ITIMER_NDLL) ; 

} 

} 

return  (value) ; 
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B.l.  Program  Names 


B.2.  Frame  Headers 


B.3.  Menus 
Capitalization 


Sun  User  Interface  Conventions 


The  window  programs  released  by  Sun  follow  some  standard  user  interface  con¬ 
ventions.  These  conventions  are  described  here  so  that,  if  you  choose,  you  can 
design  your  interfaces  with  them  in  mind. 

Here  are  some  guidelines  for  naming  programs; 

□  A  window-based  version  of  an  existing  tty-based  program  has  tool  appended 
to  the  end  of  the  existing  program.  For  example  mailtool  is  a  window- 
based  version  of  the  tty-based  program  inail(l). 

n  A  program  without  a  tty  version  should  not  end  with  tool.  Thus  the  icon  edi¬ 
tor  is  called  iconedit  and  not  icontool. 

□  Since  tools  are  normally  invoked  from  command  files  or  menus,  descriptive 
names  are  better  than  short  cryptic  ones.  Thus  iconedit  is  better  fiian  ied. 

The  frame  header  should  contain  the  name  of  the  program,  optionally  followed 
by  a  dash  and  additional  information,  as  in: 


tex-tedit  -  /tmp/file,  dir:  /usr/dg/doc 


The  words  in  menus  should  be  capitalized  as  they  would  be  in  a  chapter  heading: 


This  convention  can  be  bent  when  the  names  in  the  menu  correspond  to  already 
existing,  non-capitalized  command  names. 
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Menus  Showing  Button 
Modifiers 


When  the  behavior  of  a  panel  button  depends  on  whether  the  user  holds  down  a 
shift  key,  the  button  should  have  a  menu  summarizing  the  different  actions,  as  in 
this  menu  from  the  Reply  button  in  ma  i  1 1  o  o  1 : 


reply 

1 

Reply  (all) 

[Shifts  I 

reply.  Include 

[Ctrl]  1 

Reply  (all).  Include 

[Ctrl] [Shi  ft]  1 

Interaction  with  Standard  Standard  SunView  menus,  such  as  the  frame  menu,  should  not  be  modified. 

Menus  When  a  user  is  used  to  seeing  ‘Quit’  at  the  end  of  the  frame  menu,  it  is  confusing 

to  see  a  frame  menu  with  a  new  item  tacked  on  at  the  end.  Equally  confusing  is  a 
frame  menu  that  comes  up  with  an  item  other  than  ‘Qose’  at  the  top.  Thus, 
instead  of  deleting  an  item  from  a  standard  menu,  applications  should  render  the 
item  inactive  and  “grayed-out.”  And  instead  of  adding  a  new  item  to  a  standard 
menu,  applications  should  make  a  new  menu,  with  the  name  of  the  standard 
menu  at  the  top,  followed  by  the  application-specific  commands.  The  standard 
menu  then  becomes  a  puUright  subordinate  to  the  custom  menu,  as  in  the  exam- 
ole  below: 


Close 

Dump  Sere 

Move  ^ 

Dunp  Regi 

Resize 

Print  Dun 

Expose 

View  Dump 

Hide 

. . . 

Redisplay 

Quit 

Enable/Disable  Menu  Items  Sometimes  a  menu  has  two  different  states,  with  different  words  appearing  in  the 

same  position  in  a  menu,  depending  on  the  current  state.  When  the  two  states 
correspond  to  something  being  on  or  off,  the  words  ‘Enable’  and  ‘Disable’ 
should  be  used.  Thus  shelltool  uses  ‘Enable  Page  Mode’  and  ‘Disable  Page 
Mode’. 

Multi-Column  Menus  Overly  long  menus  should  be  avoided.  Use  menus  with  more  than  one  column 

instead. 

B.4.  Panels  The  defaults  for  panel  items  given  in  this  section  are  intended  to  promote  con¬ 

sistency  across  applications  and  provide  convenient  building  blocks  for  program¬ 
mers  who  don’t  want  to  put  a  great  deal  of  effort  into  designing  fancy  panels. 

The  intent  is  not  to  rule  out  the  use  of  non-default  panel  items. 
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Buttons  The  proper  use  of  buttons  is  to  allow  the  user  to  initiate  commands.  Button  items 

should  not  be  used  to  represent  categories,  modes  or  options  —  for  these  kinds  of 
choices  that  imply  a  change  of  state,  you  should  use  toggle,  choice  or  cycle 
items,  as  described  in  the  next  three  sections. 

When  creating  a  button,  use  the  routine  panel_button_image  ( )  to  create  a 
button-like  image,  as  in: 

[  Duimp  Screen"^ 

As  with  menu  entries,  capitalize  buttons  unless  the  button  name  matches  some¬ 
thing  else  (for  example,  dbx(l)  commands  in  dbxt  ool).  If  the  button’s  mean¬ 
ing  can  be  modified  by  ( Control  1  or  [  Shift  1  these  modifiers  should  be  indicated  in 
the  button’s  menu.  (For  an  example,  see  the  picture  of  the  Reply  menu  from 
mailtool,  at  the  top  of  the  preceding  page.) 

In  most  cases,  a  button  will  remain  visible  aU  the  time.  However,  when  a  tool 
has  different  states,  and  a  button  can  only  be  used  in  some  of  those  states,  it  is 
usually  best  to  make  the  button  invisible  when  it  can  not  be  invoked.  Thus  in 
mailtool,  the  Cancel  button  only  appears  when  a  letter  is  being  composed. 

List  of  Non-Exclusive  Choices  A  list  of  choices  in  which  more  than  one  choice  can  be  selected  at  a  time  is  best 

implemented  with  the  item  type  panel_T0GGLE.  The  default  for  toggles  is  a 
list  of  check  boxes: 

Optional  Software: 

^ Database 

□  Demos 

^ Document  Preparation  Tools 

□  Games 

ET Productivity  Tools 

The  example  shows  a  vertical  list;  vertical  or  horizontal  are  both  acceptable. 

List  of  Exclusive  Choices  A  list  of  choices  in  which  only  one  choice  can  be  selected  at  a  time  can  be 

displayed  with  all  choices  visible  or  with  only  the  current  choice  visible.  To 
show  aU  the  choices,  use  the  item  type  PANEL_CHOlCE.  The  default  for  choice 
items  is  a  list  of  square  pushbuttons,  with  the  current  choice  marked  by  a  dark¬ 
ened  pushbutton: 

Drawing  Mode:  Q  Point  Btlne  Q  Rectangle  Q  Circle  Q  Text 

To  show  only  the  current  choice,  use  PANEL_CYCLE.  This  item  type  provides  a 
symbol  consisting  of  two  circular  arrows,  which  indicate  to  the  user  that  he  can 
cycle  through  choices,  and  serves  to  distinguish  cycle  items  from  text  items: 

Category  O  SunVIew 
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Binary  Choices 


Text  Items 


Allocation  of  Function 
Between  Buttons  and  Menus 


An  item  that  is  either  on  or  off  may  be  created  using  either  panel_T0GGLE, 
PANEL_CYCLE  or  PANEL_CH0ICE.  The  picture  on  the  left  below  is  a  toggle, 
the  two  in  the  middle  are  cycles,  and  the  one  on  the  right  is  a  choice: 


Gri  d 


ShQU  Grid 


O  Yes 


Grid 


O  On 


Grid:  Bon  Q  Off 


Text  items  should  have  a  colon  after  the  label. 

For  text  items,  it  is  recommended  to  have  one  or  more  buttons  which  cause  the 
text  item’s  value  to  be  acted  on.  In  iconedit,  for  example,  the  user  first  enters 
a  filename  into  the  File:  field,  then  presses  the  Load,  Store,  or  Browse  button  in 
order  to  act  on  that  filename. 

iconedit  also  allows  the  user  to  type  ( Control-L  I.  [  Control-S  I.  or  ( Control-B  1 
into  the  File:  field  as  accelerators  for  the  buttons.  Use  of  such  accelerators 
(including  carriage  return  to  mean  “enter”)  is  not  recommended,  as  it  conflicts 
with  future  plans  for  the  use  of  non-printable  characters. 

For  the  sake  of  consistency,  whenever  a  tool  reads  from  and  writes  to  a  file,  it 
should  label  these  buttons  with  Load  and  Store . 


Selecting  a  menu  item  is  normally  the  same  as  either  selecting  a  button  or  pick¬ 
ing  from  a  choice  item.  boggletool(6),  for  example,  has  a  menu  for  restart¬ 
ing  the  game  (as  weU  as  other  things)  but  has  no  buttons.  Each  of  the  four  menu 
items  could  have  been  represented  by  a  button  instead,  lif  e(6)  does  not  have  a 
choice  item,  but  rather  lets  you  choose  a  starting  pattern  with  a  menu.  Thus  the 
question  of  when  to  use  a  button  (or  choice)  and  when  to  use  a  menu  arises.  Here 
are  some  rules  of  thumb: 


□  Items  on  the  frame  menu  should  not  be  duplicated  as  buttons,  with  the  possi¬ 
ble  exception  of  a  Quit  button  (see  next  paragraph). 

□  Some  tools  typically  run  aU  the  time,  such  as  mailtool.  Others  are  nor¬ 
mally  invoked  only  long  enough  to  do  a  job,  such  as  iconedit.  Tools  in 
the  second  category,  if  they  have  any  other  buttons,  should  also  have  a  Quit 
button. 


□  If  a  tool  has  a  commit  operation,  then  it  may  have  a  Done  button,  which  is  a 
combination  of  close^®^  plus  commit.  Thus  mailtool  has  a  Done  button. 

□  A  tool  should  never  have  a  Close  button,  since  this  operation  is  already 
available  via  both  a  menu  and  the  keyboard. 

o  If  a  custom  menu  is  provided,  the  menu  items  should  not  aU  be  duplicated  as 
panel  items  (buttons  or  choices),  boggletool  and  life  are  examples  of 
programs  that  have  functionality  in  custom  menus  that  are  not  duplicated  as 
panel  items. 

□  When  a  button  and  a  menu  item  perform  the  same  function,  their  labels 
should  be  identical. 


If  the  panel  is  in  a  subframe,  the  Done  qjeration  implies  disappearing  from  the  screen  rather  than 
closing,  since  subframes  can’t  become  iconic. 
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B.5.  Mouse  Button  Usage 

Allocation  of  Function 
Between  Mouse  Buttons 


Using  Mouse  Buttons  for 
Accelerators 


B.6.  Cursors 


B.7.  Icons 


Use  of  mouse  buttons  should  be  consistent  with  the  rest  of  SunView.  The  left 
button  should  only  be  used  to  make  selections.  The  right  button  should  only  be 
used  to  bring  up  menus. 

There  is  some  discretion  involved  in  the  use  of  the  middle  button,  however.  In 
most  of  SunView,  the  middle  button  is  used  to  adjust  a  selection.  In  text  and 
shell  windows,  for  example,  the  left  button  is  used  to  mark  the  starting  point  of  a 
selection,  and  the  middle  button  is  used  to  extend  the  selection.  Similarly,  in  a 
pixel  editor  that  allowed  you  to  select  regions,  clicking  the  left  button  on  a  region 
could  select  just  that  region,  and  clicking  the  middle  button  on  another  region 
could  add  that  region  to  the  selection.  On  the  other  hand,  in  a  tool  that  allowed 
you  to  move  objects,  the  middle  button  could  move  an  object,  and 
I  Control  l-MIDDLE  button  could  re-size  it,  which  would  be  consistent  with  the 
way  icons  and  frames  are  moved  and  re-sized.  As  a  third  alternative,  in  the 
iconedit  drawing  program  the  left  button  draws  pixels  (which  is  a  kind  of 
selecting)  and  the  middle  button  erases. 

The  best  use  of  the  middle  button  is  stiU  being  discussed.  Future  versions  of  this 
guideline  may  specify  more  exactly  how  the  middle  button  should  be  used.  For 
now,  the  most  common  use  is  to  extend  the  selection,  and  the  next-most  common 
is  to  move  a  graphic  object. 

It  is  acceptable  to  use  the  mouse  buttons  as  accelerators  for  common  operations. 
The  only  caveat  is  that  any  accelerators  should  also  be  available  from  a  menu  or 
panel  item.  Thus  in  SunView  clicking  on  a  tool  with  the  middle  button  moves 
the  tool,  but  you  can  also  move  a  tool  using  the  frame  menu. 

Some  operations,  on  the  other  hand,  cannot  be  invoked  from  a  menu  or  panel 
button.  In  such  cases  the  mouse  is  the  only  means  of  invoking  the  operation.  For 
example,  in  iconedit  you  use  the  mouse  for  drawing,  and  the  drawing  opera¬ 
tions  are  not  available  from  a  menu  or  button. 

An  application  program  should  not  do  anything  other  than  change  the  shap^  of 
the  cursor  when  the  cursor  is  moved  into  a  new  window,  textedit  presents  a 
good  example  of  using  the  cursor  to  alert  the  user  that  input  is  interpreted  dif¬ 
ferently  in  different  regions:  The  cursor  is  a  thin  diagonal  arrow  in  the 
textsubwindow,  a  fat  horizontal  arrow  in  the  scroUbar,  and  a  diamond  in  the 
scrollbar  buttons. 

Tools  should  pack  as  much  information  as  possible  into  their  icons,  clock  and 
perf  meter  are  examples  of  tools  that  make  good  use  of  icon  real  estate,  tex¬ 
tedit  is  an  example  of  a  tool  that  could  make  better  use  of  its  icon.  For  exam¬ 
ple,  it  could  contain  a  representation  of  the  text  being  editing  in  a  1  point  font. 
Small  as  that  is,  you  can  tell  at  a  glance  if  you  are  editing  C  code  or  a  mail  mes¬ 
sage. 


107  People  who  want  to  hold  the  mouse  with  their  left  hand  can  put  the  “menu  button”  on  the  left  and  the 
“selea  button”  on  the  right  by  setting  the  Lefijlanded  option  in  the  Input  category  of  de  f  ault  sedit. 
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Some  icx)ns,  like  the  round  face  used  by  clock  and  the  page  with  the  protruding 
pencil  used  by  textedit,  have  images  with  non-square  outlines.  These  icons 
have  the  area  outside  of  the  image  outline  filled  in  with  the  root  grey  pattern  so 
that  the  icons  will  blend  in  with  the  default  SunView  background.  While  this 
looks  good  when  the  background  is  in  fact  the  default  pattern,  it  is  not  recom¬ 
mended,  since  users  can  choose  an  arbitrary  background  pattern  for  SunView. 
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Converting  SunWindows  Programs  to 

SunView 

This  appendix  gives  some  guidelines  for  converting  programs  written  using 
SunWindows  to  SunView.  There  are  two  classes  of  programs  covered:  those 
that  create  a  tool  and  subwindows,  and  programs  that  call  gf  xsw_init  ( )  to 
take  over  an  existing  window  or  the  console. 

Programs  that  fall  outside  these  classes  are  probably  UNIX-style  programs  that  do 
not  use  windows  at  all.  The  conversion  of  such  programs  is  in  effect  the  subject 
of  this  whole  manual.  If  you  want  to  convert  such  a  program  to  SunView,  pay 
particular  attention  to  Chapter  2,  The  SunView  Model,  and  the  specific  discussion 
of  Notifier  interaction  under  Porting  Programs  to  SunView  in  Chapter  17,  The 
Notifier.  You  may  also  find  some  of  the  discussion  later  on  in  this  appendix 
under  Section  C.2,  Converting  Gfxsubwindow-Based  Code,  helpful. 


477 


Revision  A,  of  May  9,  1988 


478  SunView  1  Programmer’s  Guide 


C.l.  Converting  Tools 


General  Comments 


Programming  Style  Changes 

Object  typedefs 


Attribute  Value  Interface 


CAUTION 


It  is  reasonably  straightforward  to  convert  tools  that  create  windows  in  SunWin- 
dows  to  the  SunView  interface  because  they  should  already  have  the  appropriate 
architecture.  SunView  programs,  like  SunWindows  programs,  have  three  parts: 
initialization  of  static  objects,  starting  up  window  system  interaction,  and  the 
routines  that  are  called  after  the  tool  is  running  in  the  window  system. 

When  porting  to  SunView,  you  should  look  through  all  of  your  code  for  SunWin¬ 
dows  function  calls.  If  you  see  one,  the  odds  are  that  you  are  going  to  have  oth¬ 
ers.  Look  for  every  occurrence  of  the  call  and  then  change  it  to  the  new  format. 
Since  the  SunView  libraries  are  mixed  in  with  the  SunWindows  libraries,  you 
can  mix  the  two  types  of  functions  caUs,  and  not  get  any  compilation  errors.  But 
you  will  get  some  inconsistent  results. 


The  capitalized  typedefs  for  window  system  objects  (applied  to  Panels, 
Panel_items  and  Panel_settings  in  2.0  SunWindows)  have  been 
extended  to  nearly  all  SunView  objects,  including; 


Canvas 

Pixrect 

Cursor 

Pixwin 

Frame 

Rect 

Icon 

Rectlist 

Menu 

Scrollbar 

Panel 

Textsw 

Panel_item 

Tty 

Pixfont 

Window 

You  should  convert  to  using  these  data  types  in  the  interests  of  future  compatibil¬ 
ity.  See  Object  Handles  in  Chapter  3,  Interface  Outline,  for  more  information  on 
these  types. 

In  SunView,  the  attribute  value  interface,  introduced  for  panel  subwindows  in  2.0 
SunWindows,  has  been  extended  to  all  types  of  windows.  Attributes  for  all  win¬ 
dow  types  are  set  and  obtained  with  the  same  two  calls,  window_set  ( )  and 
window_get  ( ) . 

All  window  types  are  created  with  the  same  call,  window_create  ( ) . 

The  most  frequently  used  SunView  calls  use  attribute  lists,  and  therefore 
must  be  null-terminated.  SunView  will  only  complain  about  a  malformed 
attribute  list  at  run  time. 
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New  Objects 


Canvas  Subwindows 


Text  Subwindows 


Scrollbars 
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Most  of  the  data  types  in  the  above  list  are  objects  new  in  SunView.  Many 
objects  in  SunWindows  correspond  to  objects  in  SunView,  for  example: 

tool  ^  Frame 
ttysw  Tty 

Some  objects  such  as  the  graphics  subwindow  and  empty  subwindow  are  not 
supported  in  SunView^®^.  There  are  new  objects  that  partially  take  their  place. 

The  canvas  subwindow  is  a  general-purpose  drawing  subwindow,  which  can 
replace  gfit  subwindows  and  empty  subwindows.  The  size  of  the  canvas  you 
draw  on  need  not  be  the  same  as  the  size  of  the  window  it  is  displayed  in;  you 
can  create  scrollbars  to  let  the  user  adjust  the  visible  part  of  the  canvas.  For  a 
demonstration  of  the  various  canvas  attributes,  run  the  program 
lusridemo/canvasjdemo 

These  allow  for  the  display  and  editing  of  text  in  a  scrollable  window.  The  user 
can  perform  various  actions  on  the  text,  including  saving  the  text,  searching  in 
the  text,  and  editing  the  text  without  the  programmer  having  to  deal  with  these 
interactions. 

Since  there  was  no  such  window  in  SunWindows,  your  application  may  have  had 
to  use  a  gfx  subwindow,  a  set  of  panel  message  items,  or  some  strange  technique 
involving  ttYSw_inp'ut  ( >  or  piping  to  a  tty  subwindow  to  display  text;  the 
text  subwindow  can  replace  all  these  uses. 

Scrollbars  can  be  attached  to  windows.  In  particular,  the  use  of  scroUbars  with 
retained  canvases  makes  it  very  easy  to  draw  a  fixed-size  image  without  regard 
for  window  size  changes. 


108  You  can  still  compUc  and  run  code  that  uses  these,  but  Sun  does  not  intend  to  develop  them  further. 


^sun 

XT  microsystems 


Revision  A,  of  May  9, 1988 


480  SunView  1  Programmer’s  Guide 


Objects  in  Common  between 
SunView  and  Sun  Windows 


Cursors  Cursors  have  changed.  They  are  now  type  Cur  sor ,  and  all  calls  relating  to 

them  have  changed.  Type  Cursor  should  be  looked  at  as  a  pointer  to  the  stmc- 
ture  containing  the  cursor  information.  Here  is  how  you  would  define  a  cursor: 


Once  having  created  a  cursor,  you  caU  window_set  ( )  to  add  it  to  a  window, 
as  in  the  following  code  fragment: 


You  now  refer  to  aU  your  cursors  by  the  handle  you  get  from 
cur  sor_create  ( ) .  Cursors  have  their  own  create,  destroy,  copy,  set,  and  get 
routines,  as  well  as  a  number  of  attributes  with  no  corresponding  functionality  in 
SunWindows. 

Icons  Icons  have  changed.  They  follow  the  same  pattern  as  cursors;  you  define  the 

data,  create  a  pixrect,  and  then  caU  icon_create  ( )  at  run  time.  These  also 
have  their  own  create,  destroy,  set  and  get  routines,  although  there  are  fewer  attri¬ 
butes  associated  with  them. 
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Menus 


The  new  walking  menu  package  uses  the  attribute  value  interface.  It  has  many 
more  features  than  the  old  menu  package.  It  does  not  support  the  stacking  menu 
style  of  SunWindows.^^^ 


Menus  also  have  their  own  routines  and  are  created  via  function  calls  instead  of 
being  user-loaded  data  structures.  They  use  the  pointer  type  Menu  for  their  han¬ 
dles  instead  of  struct  menuptr.  One  way  to  create  them  is  to  write  a  spe¬ 
cial  menu_init  { )  proc  which  loads  them  into  their  structures  correctly.  In 
your  menu_init  ( ) ,  you  have  something  like 


ml_items  =  menu  create { 

- ^ 

MENO_STRING_ITEM, 

"insert”. 

INSERT, 

MENU_STR1NG_ITEM, 

"copy". 

COPY  , 

MENU_STRING_ITEM, 

"replace" , 

REPLACE, 

MENO_STRING_ITEM, 

"move" , 

XLATE  , 

MENO_STRING_ITEM, 

"delete" , 

DELETE, 

MENU  STRING  ITEM, 

"HELP", 

DRAW  HELP, 

0); 

V _ 

J 

Input  Events 


Menu  values  from  menu_get  { }  or  menu_show  { )  are  returned  as 
caddr_t ’s.  Be  sure  your  types  match. 

NOTE  The  old  menu_di splay  { }  andthenewmenu_show{)  routines  have  a  dif¬ 
ferent  order  for  the  arguments. 

The  inputevent  structure  has  not  changed.  However,  you  no  longer  have  to 
generate  events  yourself  in  “selectedroutines  via  calls  to 
input_reakevent  { ) .  Instead,  windows  now  have  event  handlers  that  are 
passed  pointers  to  Event  structures. 

There  are  a  number  of  macros  for  making  input  events  easier  to  deal  with  in  Sun- 
View,  so  instead  of  having  something  like  ie->ie_code  you  have 
event_id  ( ie ) ,  resulting  in  more  readable  code. 

Event  types  are  not  pointers,  so  you  have  to  distinguish  between 

Event  *ie; 

and 

Event  ie; j 

in  your  code.  You  can  use  either,  because  the  event  functions  don’t  just  manipu¬ 
late  a  handle  as,  for  example,  the  cursor  functions  do.  See  Object  Handles  in 
Chapter  3,  Interface  Outline,  for  an  explanation  of  when  handles  are  pointers  and 
when  not. 


This  is  still  available  in  the  frame  and  root  menus  if  you  disable  SunVieyv/W(dking_Menus  in 
default sedit. 
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Setting  up  Input  Event  Handling 


CAUTION 


Sigwinch  Handling 


Windows 


NOTE 


Panels 


o 


The  distinction  between  “pick”  and  “keyboard”  events  is  new  in  SunView,  hav¬ 
ing  been  added  to  support  the  notion  of  a  split  input  focus. 

Be  careful  that  when  you  are  setting  mouse  events,  you  are  modifying  the 
WIN_*  PICK_EVENTS  and  when  you  are  setting  keyboard  events  you 
modify  WlN_*_KEYBOARD_E VENTS.  You  may  get  inconsistent  results  if 
you  modify  pick  events  on  the  keyboard  mask. 


AU  the  input  events  can  be  set  up  from  the  window_create  { )  call  or 
window_set  ( )  calls.  Calls  to  win_*inputmask  ( )  are  all  replaced  by 
these  window  set()  and  window_create  ()  calls. 


Canvas  event  procedures  no  longer  need  all  the  gfx  support  for  flag  checking. 
Resize  and  repaint  events  are  separately  handled  by  the  procedures  you  supply 
via  the  CANVAS_RESlZE_PROC  and  CANVAS_REPAlNT_PROC  attributes. 
These  procedures  mean  you  should  not  try  to  catch  sigwinch  signals  (and  in  fact, 
if  you  do,  you  wiU  have  problems;  see  below). 

Making  windows  is  very  straightforward  in  SunView.  Each  window  type  has  a 
handle  —  so  instead  of  the  inconsistent  use  of  handles  and  fd’s  to  describe  a 
window  and  manipulate  it,  you  only  use  the  window  handle.  You  need  to  go 
through  your  code  and  update  all  the  reference  to  the  old  tool_...  handle  types 
in  the  code.  After  you  find  them,  locate  aU  the  function  calls  referring  to  them 
and  update  them  to  SunView  window_set  ( )  and  window_get  { )  calls. 
Almost  every  window  operation  is  supported  by  the  attribute  value  interface; 
however,  some  low-level  routines  that  are  documented  in  the  SunView  1  System 
Programmer’s  Guide  may  still  require  window  names  or  fd’s. 


window_get  ( )  is  used  to  get  an  attribute  of  a  window.  It  returns  a  caddr_t 
back  to  you,  which  must  be  cast  into  the  appropriate  type.  So  loading  something 
into  a  rect  struct  would  involve  something  like: 


Rect 

win  size; 

Canvas 

canvas ; 

canvas 

=  window  create (  base_f rame,  CANVAS,  0); 

win  size=  * ( (Rect  *) window_get (canvas,  WIN_RECT) ) ; 

1 

J 

Be  sure  to  cast  values  returned  from  get  ( )  routines  to  the  correct  type. 

The  above  *  ( (Rect  *)...)  is  needed  otherwise  you  will  get  an  ’incompatible 
type’  message  from  the  compiler. 


Most  of  the  panel  interface  was  already  using  an  attribute  value  interface  in  2.0 
SunWindows.  panel_create  ( )  panel_set  ( )  and  panel_get  { )  should 
be  changed  to  window_create  ( ) ,  window_set  { )  and  window_get  ( ) . 

The  PANEL_CU  ( )  macro  was  superseded  by  ATTR__COL  ( )  and 
ATTR_ROW  ( )  . 
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Signals 


Prompts 


If  you  are  catching  signals,  then  you  should  read  the  documentation  on  signals  in 
Section  17.2,  Restrictions,  in  the  Notifier  chapter.  There  are  several  that  the 
Notifier  now  catches  on  your  behalf. 

You  should  no  longer  be  catching  SIGWINCH  signals.  If  you  do,  your  program 
may  never  appear  on  the  screen  as  it  will  start  catching  the  signals  and  redrawing 
endlessly  on  Ae  screen,  which  may  not  be  visible. 

Instead  of  using  the  menu_prompt  { }  facility  of  SunWindows,  you  should  use 
the  alerts  package  to  prompt  the  user,  or  if  necessary  use  pop-up  subframes  and 
window_loop  (popup_frame)  when  prompting  the  user.  The^/er  example 
programs  in  Chapter  4,  Windows,  uses  the  alerts  package  to  implement  a  pop-up 
confirmer. 

menu_prompt  ( )  is  documented  here  for  completeness.  The  definitions  used 
by  menu_proinpt  ( )  are: 

struct  prompt  { 

Rect  prt_rect ; 

Pixfont  *prt_font; 
char  *prt_text; 

} 

menu_prompt (prompt,  event,  windowfd) 
struct  prompt  *prompt/ 
struct  inputevent  *event; 
int  windowfd; 

menu^prompt  ( )  displays  the  string  addressed  by  prompt->prt_text 
using  the  font  prompt->prt_f  ont .  prompt->prt_rect  is  relative  to 
windowfd.  If  either  the  r_width  or  the  r_height  fields  of 
prompt ->prt_rect  has  the  value  PROMPT_FLEXlBLE,  that  dimension  is 
chosen  to  accommodate  aU  the  characters  in  prompt->prt_t  ext . 

The  fullscreen  access  method  is  used  to  display  the  prompt.  After  displaying  the 
prompt,  menu_pr  ompt  ( )  waits  for  any  input  event  other  than  mouse  motion. 

It  then  removes  the  prompt,  and  returns  the  event  which  caused  the  return  in 
event,  windowfd  is  the  file  descriptor  of  the  window  from  which  input  is 
taken  while  the  prompt  is  up. 
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Table  C-1 

SunWindows  =>  SunView  Equivalences 

In  SunWindows 

In  Sunview 

tool  =  tool  make () 

Frame  frame  =  window__create  (NULL,  FRAME,...,  0); 

tool_parse_all 

FRAME_ARGS  or  FRAME_ARGC_PTR_ARGV 
attributes  to  window  create  (NULL,  FRAME,  ...,0) 

tool_install ( ) 
tool__select  0 
tool  destroy  0 

window  main  loop (frame); 

or,  individually. 

tool_install ( ) 

wiN_SHOW  attribute 

tool_select  () 

window  main  loopO,  notify_dispatch ( )  or  notify_start  () 

tool_destroy { > 

window  destroy  (baseframe)  or  window_done  (a«y_H'iWow) 

signal (SIGWINCH,  sigwi^ch) 

RESIZE  PROC and  REPAiNT_PROC attribute 

TOOLSW__EXTENDTOEDGE 

WIN_EXTEND_TO_EDGE 

win  grabio ( ) 

WIN_GRAB_ALL_INPUT  attribute 

struct  tool_io 

WIN  EVENT  PROC  for  window  events.  Other  events,  timers,  etc. 
handled  by  individual  calls  to  the  Notifier  to  set  up  or  interpose  specific  procs. 
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C.2.  Converting 

Gfxsubwindow-B  ased 
Code 


Basic  Steps 


Replacing  Tool  Interaction 

Styles  of  Damage  Checking 


Either  the  Notifier  Takes  Over 


Programs  that  run  in  gfxsubwindows  are  designed  to  take  over  an  existing  win¬ 
dow.  In  SunView  you  must  create  a  tool  for  such  programs  to  run  in.  One  limi¬ 
tation  of  this  approach  is  that  the  SunView  version  of  the  application  must  mn 
under  suntools;  the  old  gf  xsw_init  ( )  call  would  create  a  SunWindows 
environment  if  run  on  the  “bare”  Sun  console.  One  major  advantage  gained  by 
moving  to  SunView  is  that  your  code  can  use  scrollbars. 

□  Include  <suntool/sunview .  h>  and  <suntool/ canvas  .h>. 

□  Remove  all  window-related  #include  statements;  these  will  probably  be 
included  by  sunview .  h. 

□  Declare  a  Frame  and  a  Canvas. 

□  Replace  gf  xsw_init  ( )  with  calls  to  create  the  frame  and  canvas. 


Many  gfx  subwindow  programs  (and  many  of  the  Sun  demos)  caU 
gf  xsw_init  ( )  to  take  over  a  window,  then  run  in  a  loop  as  they  compute  and 
draw  an  image  in  the  gfx  subwindow.  At  some  point  in  the  loop  they  check  for 
damage  to  or  alteration  of  the  size  of  the  gfic  subwindow  and  handle  it  accord¬ 
ingly. 

In  SunView,  the  coexistence  of  your  program  with  the  window  system  is  less 
hidden  from  you.  Read  Chapter  2,  The  SunView  Model,  to  understand  how  this 
coexistence  works.  In  converting  programs,  you  must  ensure  the  Notifier  runs  at 
regular  intervals  so  that  window  events  such  as  close,  quit,  etc.  are  handled 
appropriately. 

Consult  Chapter  17,  The  Notifier,  for  more  information. 

You  can  either  (1)  set  up  your  program  so  that,  after  initialization,  control  passes 
to  the  Notifier,  which  you  have  set  up  to  call  your  imaging/computation  routine 
periodically,  or  (2)  let  control  continue  to  pass  to  your  code,  and  change  the  pro¬ 
gram  to  caU  the  Notifier  at  regular  intervals. 

In  the  first  case,  you  set  up  your  imaging/computation  routine  as  a  function  that 
is  called  when  a  timer  expires.  Do  this  by  calling 

not  if  Y_set_it  imer_f  unc  () .  If  you  want  your  imaging/computation  rou¬ 
tine  to  blaze  away  non-stop  (causing  other  programs  to  run  more  sluggishly),  you 
request  the  timer  function  be  called  as  soon  as  the  Notifier  has  handled  window 
events  for  you  by  giving  the  timer  the  special  value 
&NOTIFY_POLLING_ITIMER. 

.  . . s 

(void)  notify_set_itimer_func (frame,  my_animation, 

ITIMER_REAL,  &NOTIFY_POLLING_ITIMER,  ITIMER_NOLL)  ; 

^ ^ - 

If  your  code  sleep  () ’s  on  a  regular  basis,  then  you  should  be  able  to  modify  it 
so  that  the  Notifier  calls  your  imaging/computation  routine  at  the  same  interval. 
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The  program  spheres  in  Appendix  A,  Example  Programs,  is  an  example  of  this 
style  of  interaction. 

Or  Your  Code  Stays  in  Control  On  the  other  hand,  if  your  program  just  loops,  perhaps  while  ( — gf  x_r  eps ) , 

then  you  could  add  to  the  loop  a  call  to  notif  y_dispatch  ( ) .  This  will  han¬ 
dle  window  system  events  and  return. 

The  program  bounce  in  Appendix  A,  Example  Programs,  is  an  example  of  this 
style  of  interaction. 

If  you  do  this  then  your  program  has  to  detect  when  the  user  has  ‘Quit’  from  the 
menu:  see  Finishing  Up  below. 

NOTE  gf  x_reps  in  a  gfx  subwindow  program  is  set  to  a  large  number  (200,000),  but 

the  user  can  change  it  through  the  command  line  argument 
-n  number  of  repetitions. 

Handling  Damage  The  Notifier  will  handle  moving  the  window,  resizing  it,  etc.  However,  resulting 

damage  to  your  canvas  may  need  to  be  repaired.  In  the  gfx  subwindow, 
GFX_DAMAGED  is  set  whenever  a  SIGWINCH  is  received.  In  addition 
GFX_RE  START  is  set  if  the  size  of  the  window  has  changed  or  if  the  window  is 
not  retained.  GFX_DAMAGED  is  set  as  a  hint  for  you  to  cail 
gf  xsw_handlesigwinch  ( ) ,  which  would  clear  up  the  damaged  list  and  if 
the  window  was  retained  it  would  repaint  the  image  for  you.  GFX_re START  is 
set  as  a  hint  that  the  window  had  to  be  rebuilt,  either  because  of  damage  and  the 
window  is  not  retained,  or  because  of  a  resize. 

Many  situations  that  you  would  need  to  handle  yourself  in  a  gfx  subwindow  are 
rendered  superfluous  by  attributes  of  the  canvas  subwindow,  such  as 
CANVAS__AUTO_CLEAR,  etc.  For  Starters,  canvases  are  retained  by  default;  if 
your  canvas  has  scroUbars  and  is  retained,  then  you  need  not  be  concerned  with 
resize  events.  Nevertheless,  you  may  need  to  be  aware  when  you  must  rebuild  or 
repair  your  image.  Read  the  Canvases  chapter  for  more  information. 

Rather  than  setting  a  flag,  SunView  caUs  your  own  procedure  if  you  specify  one 
with  the  CANVAS_REPAINT_PROC  and  CANVAS_RESIZE_PROC  attributes. 
These  are  called  with  useful  parameters  for  their  tasks. 

You  can  modify  your  code  so  that  the  repair  activity  that  used  to  take  place  after 
noticing  the  flags  have  been  set  now  takes  place  in  the  procs  themselves,  or  you 
can  write  the  procs  so  they  set  flags  similar  to  the  GFX_RE  START  and 
GFX_REPAINT  flags  and  return,  and  leave  your  repair  code  almost  untouched. 
Or,  depending  on  your  application,  you  can  set  up  your  canvas  so  that  the  win¬ 
dow  system  handles  all  damage. 

r 

The  gf  xsw  Structure  The  gf  xsw  structure  has  fields  in  it  that  carry  useful  information.  Comparable 

information  is  available  in  SunView,  so  you  can  declare  and  setup  a  comparable 
structure  in  SunView.  The  bounce  program  in  Appendix  A,  Example  Programs, 
does  this. 

Gfx  subwindow-based  programs  use  the  gf  x->gf  xsw_rect  to  determine  the 
geometry  of  the  window  they  are  drawing  in.  Since  the  starting  point  of  this  was 
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Finishing  Up 


Miscellaneous 


relative  to  the  gfxsw,  it  was  always  0.^^®  In  SunView  the  width  and  height  of  the 
canvas  you  draw  in  are  available  through  the  canvas  attributes  CANVAS_WIDTH 
and  CANVAS_HEIGHT.  The  fields  of  the  gf  x->gf  xsw_rect  correspond  to 
these  attributes  as  follows: 

coord  r_left,  r_top;  are  both  =  0 

short  r_width,  r_height;  are  the  CANVAS_WIDTH  and 

CANVAS_HEIGHT  attributes . 

As  described  above,  you  can  use  your  own  GFX_RESTART  and  GFX_REPAINT 
flags. 

If  you  care  about  the  gfxsw  command  line  arguments,  insert  code  into  your 
program’s  argv,  argc  parsing  loop  to  handle  the  gfx  options  that  used  to  be 
taken  care  of  for  you.  The  bounce  program  has  reasonable  code  to  do  this. 

If  your  imaging  routine  is  in  control  and  periodically  calls  the  Notifier,  then  when 
the  window  is  quit  your  routine  must  know  that  this  has  occurred.  Otherwise,  the 
imaging  routine  will  continue  to  draw  in  a  window  that  has  been  destroyed,  and 
you  will  see  error  messages  like 

WIN  ioctl  number  C0146720;  Bad  file  number 

V _ 7 

until  you  kill  the  program. 

What  you  must  do  is  interpose  in  front  of  the  frame’s  destroy  event  handler  so 
that  your  program  will  know  when  the  frame  goes  away.  See  the  item  on  Getting 
Out  in  Porting  Programs  to  SunView  in  the  Notifier  chapter. 

If  your  program  exits  on  its  own,  then  it  can  call  window_done  ( )  to  destroy 
its  windows.  This  will  invoke  your  interposed  notice-destroy  routine  (which  may 
or  may  not  matter  depending  on  what  it  does).  It  will  also  call  the  standard 

Are  you  sure  you  want  to  Quit? 

alert  unless  you  set  FRAME_NO_CONFIRM. 

gf xsw_getretained  ( )  is  equivalent  to  the  CANVAS_RETAINED  attribute. 
Canvases  are  retained  by  default. 

gf  xsw_init  ( )  doesn’t  consume  the  gfxsw  command  line  options  -r, 

— n  Number_of_repetitions,  etc;  your  code  may  do  strange  things  with  its  argu¬ 
ments  to  deal  with  this. 


Many  of  the  demos  supplied  by  Sun  are  confused  on  this  point  and  go  through  unnecessary  steps. 
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Two  Examples  Listings  of  two  programs  converted  from  SunView  are  in  Appendix  A,  Example 

Programs. 

bounce  The  first  is  a  new  version  of  bouncedemo(6).  It  now  draws  its  bouncing  square 

in  a  canvas.  It  has  code  to  parse  the  standard  gfx  subwindow  command  line 
arguments.  It  preserves  the  original  while  {gfx“>gfx_reps)  {...  }loop 
structure  of  bouncedemo  by  calling  notif  y_dispatch  ( )  at  the  top  of  the 
loop.  Because  it  is  running  in  a  loop  it  must  detect  when  the  user  has  ‘Quit’  the 
window,  so  it  interposes  before  its  frame’s  destroy  routine  using 
notif  y_interpose_destroy_f  unc{ ) .  The  routine  that  is  called  just 
sets  a  flag  so  the  program  knows  to  exit  from  the  loop. 

spheres  The  second  is  a  version  of  spheres  demo  (6).  It  now  draws  its  shaded  spheres 

in  a  canvas  with  scrollbars,  so  you  can  see  aU  the  image  in  a  small  window.  It 
handles  the  notification  of  SunView  events  by  asking  the  Notifier  to  call  the 

drawing  routine  (my  animation  ( ) )  as  often  as  possible,  using 

- 

(void)  notify_set_itiiner_func (frame,  my_animation, 

ITIMER_REAL,  &NOTIFY_POLLING_ITIMER,  ITIMER_NULL) ; 

^ _ / 


Since  the  drawing  operation  is  under  the  control  of  the  Notifier,  the  Notifier  can 
control  the  program,  so  the  while  ( gf  x->gf  x_reps )  { ... }  loop  structure 
is  replaced  by  a  call  to  window_main_loop  ( ) ;  this  win  terminate  the  pro¬ 
gram  when  the  user  chooses  ‘Quit’  from  the  frame  menu. 

Detecting  when  the  Program  is  spheres  detects  when  it  is  made  iconic  by  interposing  in  fi-ont  of  the  frame’s 

Iconic  client  event  handler  using  notif  y_interpose_event_func  ( ) .  The  rou¬ 

tine  that  is  called  calls  the  normal  event_f  unc,  then  checks  to  see  if  the  frame 
has  changed  state:  if  it  has  been  closed  it  turns  the  notify  timer  off  altogether,  so 
the  drawing  routine  is  no  longer  called;  if  it  has  been  opened  the  timer  is  set  back 
to  immediate  polling. 

bounce  should  do  this  also  —  there  is  little  point  in  drawing  when  iconic  unless 
you  are  drawing  a  single  compute-intensive  image. 
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action  procedure  for  menu  item,  229 
alarm(3),  285 
alert,  199 

arrow,  201 

beeping,  202 

buttons,  201 

components  of,  201 

controlling  beeping,  208 

creation,  202 

described,  199 

example  program,  389 

interface  summary,  316 

messages  and  simple  buttons,  203 

position  of,  202 

table  of  attributes,  316 

table  of  functions,  318 

text  message,  201 

types  of  buttons,  204 

use  with  blocking  pop-ups,  47 

uses  of,  201 

using  trigger  events,  206 
alert  attributes,  316 

ALERT_BUTTON,  316 
ALERT_BUTTON_FONT,  316 
ALERT_BUTTON_NO,  204, 316 
ALERTJBUTTON_YE  S,  204,  316 
ALERT_MESSAGE^  203 
ALERT_MESSAGE_FONT,  316 
ALERT_MESSAGE_STRINGS,  316 
ALERT_MESSAGE_STRINGS_ARRAY_P  TR,  3 1 6 
ALERT_NO_BEEPINGi  208, 316 
ALERT_OPTIONAL,  317 
ALERT_P  OS  I T I  ON,  3 17 
ALERT_TRIGGER,  207,  317 
alert  functions,  318 

alert_prompt  ( ) ,  202, 318 
possible  status  values,  202 
ASCn  events,  86 

asynchronous  signal  notification,  293 
ATTR_COL,  54, 160, 309 
ATTR_COLS,  310 
ATTR_LIST,311 
ATTR_ROW,  54, 160, 309 
ATTR_R0WS,  310 
attribute  functions 

attr  create_list  () , 310 


attribute  lists 

creating  reusable  lists,  310 
default  attributes,  311 
maximum  size,  29,  3 1 1 
overview,  28 
utilities,  309 
attribute  ordering,  55 
for  canvases,  69 
in  text  subwindow,  132 

B 

base  frame,  16 
boimdary  manager,  19 
button  image  constructor,  168 
button  panel  item,  158,  167  thru  169 
buttons  with  menus,  168 

c 

callback  procs,  20 

callback  style  of  programming,  20 

canvas,  61 

attribute  ordCT,  69 
automatic  sizing,  69 
backing  pixrect,  66 

canvas  space  vs.  window  space,  70,  98 

color  in  canvases,  72 

coordinate  system,  65 

default  input  mask,  70 

definition  of,  61 

handling  input,  70 

interface  summary,  319 

model,  65 

monochrome  in  multiple  plane  groups,  125 
non-retained,  66 
pixwin,  63,  65 
repaint  procedure,  66 
repainting,  66 
resize  procedure,  67 
retain^,  66 
scrolling,  64 
table  of  attributes,  319 
table  of  functions  and  macros,  320 
tracking  changes  in  size,  67 
writing  your  own  eveat  procedure,  70 
canvas  attributes,  319 

CANVAS_AUTO_CLEAR,  66,  319 
CANVAS_AUTO_EXPAND,  69,  319 
CANVAS  AUTO  SHRINK,  69,  319 
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canvas  attributes,  continued 

CANVAS_FAST_MONO,  319 
CANVAS_FIXED_IMAGE,  67,  319 
CANVAS_HEIGHT,  65,  319 
CANVAS_MARGIN,  65,  319 
CANVAS_PIXWIN,  65,  103,  319 
CANVAS_REPAINT_PROC,  66,  319 
CANVAS_RESIZE_PROC,  319 
CANVAS_RETAINED,  66, 319 
CANVAS_WIDTH,  65,  69,  319 
canvas  functions  and  macros,  320 
canvas_event  () ,  71,  98, 320 
canvas_pixwin  (),  63,  65,  103,  320 
canvas_window__event  () ,  70, 320 
CAPSMASK,  96, 97 
character  unit  macros 

ATTR_COL,  54, 160, 309 
ATTR_COLS,  310 
ATTR_ROW,  54,  160,  309 
ATTR_ROWS,  310 

child  process  control  using  the  Notifier,  288 

choice  panel  item,  158, 170  thru  176 

classes  of  windows,  16 

client  handle  used  by  the  Notifier,  287 

clipping  in  a  pixwin,  1 12 

code  examples,  see  example  programs 

color,  113 

advanced  colormap  manipulation  example  program,  441 

animation,  122,  447 

backgroimd  color  of  pixwin,  115 

color  during  fullscreen  access,  119 

colormap,  1 13 

colormap  access,  118 

colormap  segment,  114 

cursors  and  menus,  1 19 

default  colormap  segment,  1 15 

determining  if  display  is  color,  119 

example  programs,  44l 

fast  color  change,  1 14 

foreground  color  of  pixwin,  1 15 

FRAME_BACKGROUND_COLOR,  115 

FRAME_FOREGROUND_COLOR,  115 

FRAME_INHERIT_COLORS,  115 

grayscale  compatibility,  120 

hardware  double-buffering,  122 

in  canvases,  72 

introduction,  113 

one  colormsqj  segment  per  window,  116 
showcolor,  116 

software  double-buffering,  120, 122 
software  double-buffering  example  program,  447 
table  of  color  functions,  360 
using  color,  119 

compiling  SunView  programs,  27 
confirmation 

FRAME_NO_CONFIRM,  382 
control  structure  in  Notifier-based  programs,  21 
converting  existing  programs  to  use  the  Notifier,  303 
converting  programs  to  SunView 
attribute-value  interface,  478 
cursors,  480 

equivalent  SunWindows  routines,  484 


converting  programs  to  SunView,  continued 
gfx  subwindow-based,  485 
gfx  subwindow-based  examples,  454 
icons,  480 
input  events,  481 
menus,  481 
new  objects,  479 

non-window  based  programs,  477 
panels,  482 
prompts,  483 
signals,  483 

SunWindows-based,  477 
typedefs,  478 
windows,  482 

write  a  prompt. . .  read  a  reply,  216 
CTRLMASK,  96,  97 
cursor,  253 

crosshair  border  gravity,  258 
crosshair  gap,  258 
crosshair  length,  258 
crosshairs,  256 
definition  of,  253 
fullscreen  crosshairs,  258 
hot  spot,  257 
interface  summary,  321 
rasterop,  257 

setting  position  of  mouse  cursor,  91 
table  of  attributes;  321 
table  of  functions,  323 
cursor  attributes,  321 

CURSOR_CROSSHAIR_BORDER_GRAVITy,  258,  321 
CURSOR_CROSSHAIR_COLOR,  321 
CURSOR_CROSSHAIR_GAP,  258,  321 
CURSOR_CROSSHAIR_LENGTH,  258 
CURSOR_CROSSHAIR_OP,  321 
CURSOR_CROSSHAIR_THICKNESS,  321 
CURSOR_FULLSCREEN,  258,  321 
CDRSOR_HORI Z_HAIR_BORDER_GRAVITy,  321 
CURSOR_HORIZ_HAIR_COLOR,  321 
CDRSOR_HORIZ_HAIR_GAP,  321 
CURSOR_HORIZ_HAIR_OP,  321 
CURSOR_HORIZ_HAIR_THICKNESS,  321 
CURSOR_IMAGE,  256,  257,  321 
CURSOR_OP,  257,  321 
CURSOR_SHOW_CROSSHAIRS,  321 
CURSOR_SHOW_CDRSOR,  321 
CURSOR_SHOW_HORIZ_HAIR,  321 
CURSOR_SHOW_VERT_HAIR,  321 
CURSOR_VERT_HAIR_BORDER_GRAVITY,  322 
CURSOR_VERT_HAIR_COLOR,  322 
CURSOR_VERT_HAIR_GAP,  322 
CURSOR_VERT_HAIR_OP,  322 
CURSOR_VERT_HAIR__THICKNESS,  322 
CURSOR_XHOT,  257,  322 
CURSOR_YHOT,  257, 322 
cursor  constants 

CURSOR_TO_EDGE,  258 
cursor  functions,  323 

cursor_copy  () ,  255, 323 
cursor_create  () ,  255, 323 
cursor_ciest  roy  ( } ,  255,  323 
cursor_get  { ) ,  255, 323 
cursor  set  < ) ,  255,  323 
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CURSOR_TO_EDGE,  258 
cycle  panel  item,  174 

D 

data  types,  324 
caddr_t,  28 
object  handles,  28 
opaque,  28 

default  colonnap  segment,  115 
default  system  font,  41 
DEFINE_ICON_FROM_IMAGE  ( ) ,  40,  262 
DESTROY_CHECKING,  300 
DESTROY_CLEANOP,  300 
DESTROY_PROCESS_DEATH,  300 
destroying  windows 

FRAME_NO_CONFIRM,  382 
destruction  of  objects,  300 
disable  Quit  confirmation 

FRAME_NO_CONFIRM,  41, 382 
dispatching  events 

calling  the  Notifier  explicitly,  303 
calling  the  Notifier  implicitly,  303 
display 

batching,  110 

canvases  and  gfxsw’s  in  multiple  plane  groups,  125 
determining  if  in  color,  119 
enable  plane,  124 
locking,  109 

locking  and  batching  interaction,  112 
overlay  plane,  124 
plane  group,  124 
software  double-buffering,  120 
speed,  108 

distribution  of  input  in  a  window,  90 

E 

event 

ASCn  event  codes,  86 

canvas  space  vs.  window  space,  70,  98 

definition  of,  80 

function  key  event  codes,  88 

keyboard  focus  event  codes,  88 

META  event  codes,  86 

mouse  button  event  codes,  86 

mouse  motion  event  codes,  86 

panel  space  vs.  window  space,  193 

reading  events  explicitly,  97 

relationship  to  Notifier,  20 

repaint  and  resize  event  codes,  87 

shift  key  event  codes,  89 

timeout,  294 

using  an  event  with  alerts,  206 
window  entry  and  window  exit  event  codes,  87 
event  codes,  330,  82 
BUT  0, 86 
KBD_DONE,  88 
KBD_REQUEST,  88 
KBD_USE,  88 
KEY_LEFT,  88 
KEY_RIGHT,  88 
KEY_TOP,  88 
LOG  DRAG,  70,  86 


event  codes,  continued 
LOC_MOVE,  86 
LOC_RGNENTER,  87 
LOC_RGNEXIT,  87 
LOC_STILL,  86 
LOC_TRAJECTORY,  86 
LOCJVINENTER,  87 
LOC_WINEXIT,  87 
MS_LEFT,  86 
MS_MIDDLE,  86 
MS_RIGHT,  86 

PANEL_EVENT_CANCEL,  190 
PANEL_EVENT_DRAG_IN,  190 
PANEL_EVENT_MOVE_IN,  190 
SCROLL_REQUEST,  80 
SHIFT_CAPSLOCK,  89 
SHIFT_CTRL,  89 
SHIFT_LEFT,  89 
SHIFT_LOCK,  89 
SHIFT_META,  89 
SHIFT_RIGHT,  89 
WIN_REPAINT,  70,  87 
WIN_RESIZE,  70,  87,  299 
WIN_STOP,  88 
event  descriptors,  333 

WIN_ASCII_EVENTS,  70,  90,  333 
WIN_IN_TRANSIT_EVENTS,  90,  333 
WIN_MOUSE_BUTTONS,  90,  333 
WIN_NO_EVENTS,  90,  333 
WIN_DP_ASCII_EVENTS,  90,  333 
WIN_DP_EVENTS,  90,  333 
event  handling 

at  the  Notifier  level,  288 
in  canvases,  70 
in  panels,  189 
event  procedure 
form  of,  81 

writing  your  own  for  a  canvas,  70 
writing  your  own  for  a  panel  item,  191 
event  state  retrieval  macros 
event_act ion  ( ) ,  96 
event_ctrl_is_down  () ,  96 
event_is_ascii  0,96 
event_is_button  ( ) , 96 
e vent_i  s_down  ( ) ,  96 
event_is_key_left  () ,  96 
event_is_key_right ( ) ,  96 
e vent_i s_key_top ( ) ,  96 
event_is_meta  ( ) ,  96 
event_is_up  () ,  96 
event_meta_is_down  <) ,  96 
event_shift_is_down  () ,  96 
event_shiftmask ( > ,  96 
event_t ime ( ) ,  96 
e vent_x ( ) ,  96 
event_y ( ) ,  96 
event  state  setting  macros 

event_set._down  ( ) ,  97 
event_set_id  ( ) ,  97 
event_set_shifttnask  () ,  97 
e  vent_s  et_t  ime  () ,  97 
event_set_up  ( ) ,  97 
event  set  x(),97 
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event  state  setting  macros,  continued 
evBnt_set_y  ( ) ,  97 
event  stream,  80 
example  programs,  389 
animatecolor,  122, 447 
bounce,  454 
color  manipulation,  441 
coloredit,  118, 441 
colormap  manipulation,  441 
converting  terminal-based  programs,  216 
creating  menus,  416 
detool,  430 

discussion  of  image  J}rowser_l  program,  50 
discussion  of  image_browser_2,  53 
discussion  of  simple  file  manager,  44 
filer,  44. 389 
fontjnenu,  416 

gfx  subwindow-based  demos  converted  to  SunView,  454 

gfxsw_init  to  SunView,  454, 461 

image_browser_l ,  401 

image _browser_2, 406 

list  files  in  tty  subwindow,  42 

minimal  SunView  program,  37 

not.ify_dispatch  () ,  216, 454 

notify_set_itimer_func  () ,  461 

resize_demo,  52,  299, 425 

row/column  space  in  a  window,  406 

show  color,  116 

simple  file  manager,  389 

simple  panel  window,  39 

spheres,  461 

subwindow  layout,  401 

tty  subwindow  escape  sequences,  412 

tty  subwindow  I/O,  412 

tty  jo,  412 

typein,  437 

F 

f  cntl(2),  286, 290 
file  descriptor  usage,  57 
filer,  44 

flow  of  control  in  Notifier-based  programs,  21 
font  functions 

pf_def ault  ( ) ,  41,  106 
pf_open  0,41 
frame 

command  line  fi’ame  attributes,  386 
definition  of,  1 6 
fitting  around  subwindows,  41 
firame  header,  18 

layout  of  subwindows  within  a  frame,  51, 52,  299,  425 
menus,  18 

modifying  destruction  using  the  Notifier,  299 
modifying  open/close  using  the  Notifier,  297 
table  of  attributes,  382 
frame  attributes,  382 

FRAME_ARGC_PTR_ARGV,  40,  382 
FRAME_ARGS,  55,  382 
FRAME_BAGKGROUND_COLOR,  115,  382 
FRAME_CLOSED,  382 
FRAME_CLOSED_RECT,  382 
FRAME_CMDLINE_HELP_PROC,  382 
FRAME  CURRENT_RECT,  382 


frame  attributes,  continued 

FRAME_DEFAOLT_DONE_PROC,  382 
FRAME_DONE_PROC,  382 
FRAME_EMBOLDEN_LABEL,  382 
FRAME_FOREGROUND_COLOR,  115,  382 
FRAME_ICON,  40,  382 
FRAME_INHERIT_COLORS,  115,  382 
FRAME_LABEL,  40,  382 
FRAME_NO_CONFIRM,  41,  382 
FRAME_NTH_SUBFRAME,  383 
FRAME_NTH_SUBWINDOW,  383 
FRAME_NTH_WINDOW,  383 
FRAME_OPEN_RECT,  383 
FRAME_SHOW_LABEi:,,  40,  45,  383 
FRAME_SUBWINDOWS_ADJUSTABLE,  383 
f  ree(3),  311 
function  keys,  88 

G 

generate  procedure 
for  menu,  244 
for  menu  item,  243 
for  pull-right,  246 

generate  procedure  operation  parameter  values 
MENU_DI SPLAY,  242 
MENU_DISPLAY_DONE,  242 
MENU_NOTIFY,  242 
MENU_NOTIFY_DONE,  242 
getitimer(2),  285 
gfx  subwindow 

pw_use_fast_monochrome  () ,  125 
converted  demo  programs,  454, 461 
converting  to  SunView,  485 
demo  programs  converted  to  SimView,  454 
monochrome  in  multiple  plane  groups,  125 

H 

header  files 

overview,  27 

<suntool /canvas . h>,  61 
<suntool/icon.h>,  261 
<suntool/inenu  .h>,  221 
<  suntool /panel  .h>,  153 
<suntool/scrollbar  .h>,  165,  267 
<suntool/seln  .h>,  279 
< suntool /sunview.h>,  27 
< suntool /text sw.h>,  129 
<suntool/tty  .h>,  211 
<sunwindow/attr.h>,  311 
<sunwindow/cms_mono.h>,  115 
<sunwindow/pixwin.h>,  101 
<sunwindow/rect . h>,  52 
<sunwindow/win_cursor .h>,  253 
<sunwindow/win_input . h>,  77 
<sunwindow/window_hs  .h>,  77,  101 

I 

icon,  261 

definition  of,  19 

interactive  editor  for  icon  images,  262 
interface  summary,  328 
Loading  Icon  Images  At  Rim  Time,  263 
modifying  the  icon’s  image,  263 


o 
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icon,  continued 

table  of  attributes,  328 
table  of  functions  and  macros,  329 
icon  attributes,  328 
ICON_FONT,  328 
ICON_HEIGHT,  328 
ICON_IMAGE,  328 
ICON_IMAGE_RECT,  328 
ICON_LABEL,  328 
ICON_LABEL_RECT,  328 
ICON_WIDTH,  328 
icon  fimctions  and  macros,  329 

DEFINE_ICON_FROM_IMAGE  () ,  40,  262,  329 
icon_create  ( ) ,  262,  329 
icon_destroy  ( > ,  329 
icon_get  ( ) ,  329 
icon_set  ( ) ,  329 
image_browser_l,  50 
image _browser_2,  53 
images 

in  icons,  262 
in  menus,  227 
mpr_static  ( ) ,  227,  262 
using  images  generated  with  iconedit,  227, 262 
include  files  —  see  “header  files”,  27 
initiating  event  processing,  35 
input,  77 

ASCE  events,  90,  333 
designee,  92 
environment,  79 
event  descriptors,  90 
event  macros,  96,  97 
flow  of  control,  97 
focus,  91 
focus  control,  91 
grabbing  all  input,  92 
in  canvases,  70 
interface  summary,  330 
keyboard  focus,  88,  91 
keyboard  mask,  91 
mask,  91  thru  95 
mouse  motion,  86 
pick  focus,  91 
pick  mask,  91 
reading,  97 
recipient,  92 

refusing  the  keyboard  focus,  88 
releasing,  92 
shift  state,  97 
state,  96 

table  of  event  codes,  82,  330 
table  of  event  descriptors,  333 
table  of  input-related  window  attributes,  334 
Virtual  User  Input  Device  (VUID),  80 
input  event  codes 

SCROLL_REQUEST,  83,  331 
interposition,  287,  296  thru  302 
interval  timers,  294  thru  296 
ioctl(2),  286 
it  interval  struct,  296 


K 

KBD_DONE,  88 
KBD_REQUEST,  88 
KBD_USE,  88 
KEY_LEFT,  88 
KEY_RIGHT,  88 
KEY_TOP,  88 
keyboard  focus,  88 

L 

layout  of  items  within  a  panel,  160 
layout  of  subwindows  within  a  frame,  51 
libraries  used  in  SunView,  27 
LOC_DRAG,  86 
LOC_MOVE,  86 
LOC_RGNENTER,  87 
LOC_RGNEXIT,  87 
LOC^STILL,  86 
LOC_TRAJECTORY,  86 
LOC_WINENTER,  87 
LOC_WINEXIT,  87 
locator,  see  mouse 
locator  motion  event  codes,  86 

M 

Menu,  327 
menu 

attributes  to  add  pre-existing  menu  items,  235 

basic  usage,  224 

callback  procedures,  240 

client  data,  228 

default  selection,  249 

destruction,  238 

display  stage  of  menu  processing,  241 

example  program,  416 

for  panel  items,  158 

generate  procedure,  242 

inactive  items,  231 

initial  selection,  249 

interface  summary,  335 

notification  stage  of  menu  processing,  242 

notify  procedure,  228,  247 

puU-right,  221 

searching  for  a  menu  item,  239 
shadow,  228 
table  of  attributes,  335 
table  of  functions,  341 
table  of  maiu  item  attributes,  339 
user  customizable  attributes,  250 
walking,  221 
menu  attributes,  335 

MENU_ACTION_IMAGE,  237,  335,  339 
MENU_ACTION_ITEM,  237,  335, 339 
MENU_ACTION_PROC,  339 
MENU_APPEND_ITEM,  235,  335,  339 
MENU_BOXED,  231, 250, 335,  339 
MENU_CENTER,  335,  339 
MENU_CLIENT_DATA,  228,  335,  339 
MENU_COLUMN_MAJOR,  335 
MENU_DEFAULT,  335 
MENU  DEFAULT  ITEM,  249,  335 
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menu  attributes,  continued 

MENa_DEFAULT_SELECTION,  249,  250,  335 
MENU_DESCEND_FIRST,  239,  335 
MENU_FEEDBACK,  234,  339 
MENU_FIRST_EVENT,  335 
MENU_FONT,  228, 233, 250, 335, 339 
MENU_GEN__PROC,  242,  243,  244, 335,  339 
MENU_GEN_PROC_IMAGE,  339 
MENU_GEN_PROC_ITEM,  242,  339 
MENU_GEN_PULLRIGHT.  246,  339 
MENU_GEN_PULLRIGHT_IMAGE,  237,  246,  335,  339 
MENU_GEN_PULLRIGHT_ITEM,  237,  246,  335,  339 
MENU_IMAGE,  339 

MENU_IMAGE_ITEM,  225,  229,  237,  336, 339 
MENU_IMAGES,  227, 237, 336 
MENU_INACTIVE,  231,  339 
MENU_INITIAL_SELECTION,  249,  250, 336 
MENU_INITIAL_SELECTION_EXPANDED,  250,  336 
MENa_INITIAL_SELECTION_SELECTED,  250,  336 
MENU_INSERT,  234,  235,  336 
MENU_INSERT_ITEM,  235,  336 
MENU_INVERT,  340 
MENU_ITEM,  226, 233, 237, 336 
MENU_JUMP_AFTER_NO_SELECTION,  250,  336 
MENU_JUMP_AFTER_SELECTION,  250,  336 
MENU_LAST_EVENT,  336 
MENU_LEFT_MARGIN,  230,  250,  336,  340 
MENU_MARGIN,  230, 231, 250, 336,  340 
MENU_NCOLS,  231, 336 
MENU_NITEMS,  233,  336 
MENU_NOTIFY_PROC,  337 
MENU_NROWS,  23 1, 336 
MENU_NTH_ITEM,  233,  337 
MENU_PARENT,  337,  340 
MENU_PULLRIGHT,  226,  233,  340 
MENU_PULLRIGHT_DELTA,  250,  337 
MENU_PULLRIGHT_IMAGE,  237, 337,  340 
MENU_PULLRIGHT_ITEM,  236, 237, 337, 340 
MENU_RELEASE,  234,  238,  340 
MENU_RELEASE_I  MAGE,  340 
MENU_REMOVE,  235,  337 
MENU_REMOVE_ITEM,  235,  337 
MENU_REPLACE,  235,  337 
MENU_REPLACE_ITEM,  235, 337 
MENU_RIGHT_MARGIN,  230, 250, 337, 340 
MENU_SELECTED,  337,  340 
MENU_SELECTED_ITEM,  249,  337 
MENU_SHADOW,  228,  232,  250,  337 
MENU_STAY_UP,  337 
MENU_STRING,  226,  233,  340 
MENU_STRING_ITEM,  225, 229,  237,  337,  340 
MENU_STRINGS,  237,  337 
MENU_TITLE_IMAGE,  228, 338 
MENO_TITLE_ITEM,  228,  338 
MENU_TYPE,  338, 340 
MENU_VALID_RESULT,  338 
MENU_VALDE,  225,  229, 340 
menu  callback  procedures 
generate  procedures,  242 
notify  and  action  procedures,  247 
menu  data  types 
Menu,  327 

Menu_generate,  242,  327 
Menu  item,  327 


menu  functions,  341 

menu_create  ( ) ,  224, 341 
menu_create_item  0 , 234, 341 
menu_destroy  () ,  238,  341 
menu_destroy_with_jproc  ( ) ,  238,  341 
menu_find  0 , 239, 341 
menu_get  ( ) ,  224, 341 
menu_return_item  0 , 342 
menu_return_value  ( ) ,  342 
menu_set  { ) ,  224, 341 
menu_show  ( ) ,  224, 229, 240, 244, 341 
menu_show_using_fd  0 , 342 
menu  item 

action  procedure,  229, 247 
generate  procedure,  229 
margins,  230 
table  of  attributes,  339 
value  of,  229 

menu  package,  221  thru  251 
menu  processing 

display  stage,  240 
notification  stage,  240 
MENU_DI  SPLAY,  242 
MENU_DISPLAY__DONE,  242 
Menu_generate,  242, 327 
Menu_iteni,  327 
MENU_NOTIFY,  242 
MENU_NOTIFY_DONE,  242 
menu_prompt  ( ) ,  483 
message  panel  item,  158,  167 
META  events,  86 
META_SHIFT_MASK.  96,  97 
mouse 

evait  codes  for  mouse  buttons,  86 
setting  position  of  mouse  cursor,  91 
tracking,  86 

mpr_static  () ,  227,  262 
MS_LEFT,  86 
MS_MIDDLE,  86 
MS_RIGHT,  86 

multiple  views  in  text  subwindows,  147 

N 

namespaces  reserved  by  SunView,  30 
Notifier 

asynchronous  signal  notification,  293 
base  event  handler,  296 
child  process  control  events,  288 
client  handle,  287 

converting  existing  programs  to  use  the  Notifier,  303 
debugging,  306 

discarding  the  default  action,  299 

error  handling,  305 

event  handler  function,  287 

flow  of  control  in  Notifier-based  programs,  2l 

interposing  on  frame  open/close,  297 

interposing  on  resize  events,  299, 425 

interposition,  287 

overview,  20, 287 

pipes,  290 

polling,  295 
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Notifier,  continued 

prohibited  signals,  286 
prohibited  system  calls,  285 
registering  an  event  handle,  288 
restrictions  imposed  on  clients,  285 
signal  events,  291 
table  of  functions,  343 
when  to  use,  285 
Notifier  functions,  343 

notify_default_wait3  () ,  288, 343 
notify_dispatch  0 , 303, 343 
not ify_do_di spat ch  () ,  216,  304,  343 
not  if  y_dump  ( ) ,  306 

notify_interpose_destroy_func  () ,  299,  343 
notify_interpos6_event_func  {) ,  297,  343 
notify_interpose_wait3_func {) ,  215 
notify_itimer_value  () ,  285,  296,  343 
notify_next_destroy__func  () ,  343 
notify_next_event_f unc  ( > ,  297, 344 
notify_no_dispatch  () ,  304,  344 
notify_perror  () ,  305, 344 
notify_set_destroy_func  ( ) ,  286,  344 
notify_set_exception_f  unc  ( ) ,  286, 344 
notify_set_input_func  ( ) ,  286,  290,  292, 344 
notify_set_itiiner_func  (> ,  285, 294, 295, 296, 344 
notify_set_output_func  () ,  286, 292, 345 
notify_set_signal_func  () ,  88,  287, 291,  345 
notify_set_wait3_func  (} ,  286,  288,  345 
not  ify_start  < ) ,  345 
notify_stop  () ,  304,  345 
notify_veto_destroy  () ,  300,  345 
notify  procediue 
for  menu,  228 
for  panel  button  items,  167 
for  panel  choice  items,  172 
for  panel  slider  items,  184 
for  panel  text  items,  180 
for  panel  toggle  items,  176 
notify  procs,  20 

NOTIFY_DONE,  288,  289,  290,  295,  300,  302 
notify_errno,  305 
Notify_error,  305 
NOTIFY_ERROR_ABORT,  306 
NOTIFY_FUNC_NOLL,  291,  305 
NOTIFY_IGNORED,  288,  289, 293 
NOTIFY_OK,  305 
NOTIFY_POLLING_ITIMER,  295 

o 

object 

definition  of,  9 
destruction  of,  300 
handle,  28 

non- window  visual  objects,  11 
window  objects,  1 1 
opening  a  font,  41 

P 

painting  panels  and  panel  items,  185 
panel,  153,  327 

action  functions,  190 
attributes,  346 


panel,  continued 

attributes  applying  to  all  item  types,  160 

caret,  179 

caret  item,  179 

caret  manipulation,  180 

creation,  159 

data  types,  327 

default  event-to-action  mq>ping,  189 

definition  of,  158 

evrait  handling  mechanism,  189 

interface  summary,  346 

item  label,  158 

item  menu,  158 

iterating  over  all  itans  in  a  panel,  188 
modifying  attributes,  162 
painting,  185 

panel  space  vs.  window  space,  193 
panel-wide  item  attributes,  163 
positioning  items  within  a  panel,  160 
retrieving  attributes,  163 
simple  panel  window  example,  39 
table  of  attributes,  346 
table  of  functions  and  macros,  353 
table  of  generic  panel  item  attributes,  347 
using  scrollbars  with,  165 
panel  attribute  settings 

PANEL_ALL,  170, 176, 180,  184 
PANEL_CLEAR,  185 
PANEL_C0RRENT,  170 
PANEL_DONE,  184 
PANEL_HORIZONTAL,  162, 178 
PANEL_INVERTED,  172 
PANEL_MARKED,  172 
PANEL_NG_CLEAR,  185 
PANEL_NON_PRINTABLE,  180 
PANEL_NONE,  170, 172, 176,  180, 185 
PANEL_SPECIFIED,  180 
PANEL_VERTICAL,  162,  170,  178 
panel  attributes,  346 

PANEL_ACCEPT_KEYSTROKE,  189,  190, 346,  347 
PANEL_BACKGROUND_PROC,  189, 190,  346 
PANEL_BLINK_CARET,  164,  346 
PANEL_BUTTON,  160 
PANEL_CARET_ITEM,  162,  179,  346 
PANEL_CHOICE,  160 
PANEL_CHOICE_FONTS,  349 
PANEL_CHOICE_IMAGE,  164, 349 
PANEL_CHOICE_IMAGES,  170,  349 
PANEL_CHOICE_STRING,  349 
PANEL_CHOICE_STRINGS,  170,  349 
PANEL_CHOICE_X,  349 
PANEL_CHOICE_XS,  170,  349 
PANEL_CHOICE_Y,  349 
PANEL_CHOICE_YS,  349 
PANEL_CHOICE_YS,,  170 
PANEL_CHOICES_BOLD,  349 
PANEL_CLIENT_DATA,  188,  347 
PANEL_CYCLE,  160 

PANEL_DISPLAY_LEVEL,  170,  176,  349 
PANEL_EVENT_PROC,  189, 191, 346,  347 
PANEL_FEEDBACK,  172,  349 
PANEL_FIRST_ITEM,  188,  346 
PANEL_ITEM_RECT,  347 
PANEL  ITEM  X,  160,  347 
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panel  attributes,  continued 

PANEL_ITEM_X_GAP,  161;  346 
PANEL_ITEM_y,  160,  347 
PANEL_ITEM_Y_GAP,  161,  346 
PANEL_LABEL_BOLD,  163,  346,  347 
PANEL_LABEL_FONT,  347 
PANEL_LABEL_IMAGE,  167, 347 
PANEL_LABEL_STRING,  167,  347 
PANEL_LABEL_X,  162,  347 
PANEL_LABEL_y,  162,  347 
PANEL_LAy0UT,  162,  163, 170, 178, 346, 347, 349 
PANEL_MARK_IMAGE,  349 
PANEL_MARK__IMAGES,  170,  350 
PANEL_MARK_X,  350 
PANEL_MARK_XS,  170, 350 
PANEL_MARK_y,  350 
PANEL_MARK_yS,  170,  350 
PANEL_MASK_CHAR,  352 
PANEL_MAX_VALUE,  184,  185,  351 
PANEL_MENU_CHOICE_FONTS,  347 
PANEL_MENa_CHOICE_IMAGES,  347 
PANEL_MENU_CHOICE_STRINGS,  183,  347 
PANEL_MENa_CHOICE_VALUES,  183,  348 
PANEL_MENU_MARK_IMAGE,  178,  350 
PANEL_MENU_NOMARK_IMAGE,  178,  350 
PANEL_MENU_TITLE_FONT,  348 
PANEL_MENU_TITLE_IMAGE,  348 
PANEL_MENU_TITLE_STRING,  348 
PANEL_MESSAGE,  160 
PANEL_MIN__VALUE,  184,  185,  351 
PANEL_NEXT_ITEM.  188,  348 
PANEL_NOMARK_IMAGE,  350 
PANEL_NOMARK_IMAGES,  170,  350 
PANEL_NOTIFy_LEVEL,  180, 184,  351,  352 
PANEL_NOTIFy_PROC,  167, 172, 180,  348 
PANEL_NOTIFy_STRING,  180,  352 
PANEL_PAINT,  163, 185, 348 
PANEL_PARENT_PANEL,  348 
PANEL_SHOW_ITEM,  164,  179,  348 
PANEL_SHOW_MENU,  163,  346,  348 
PANEL_SHOW_MENU_MARK,  172,  350 
PANEL_SHOW_RANGE,  184,  351 
PANEL_SHOW_VALUE,  184,  351 
PANEL_SLIDER_WIDTH,  184,  351 
PANEL_TEXT,  160 
PANEL_TOGGLE,  160 
PANEL_TOGGLE_VALUE,  350 
PANEL_VALUE,  162, 163, 185, 350, 351, 352 
PANEL_VALUE_DISPLAy_LENGTH,  178,  352 
PANEL_VALUE_FONT,  351,  352 
PANEL_VALUE_STORED_LENGTH,  179,  352 
PANEL_VALUE_X,  162,  348 
PANEL_VALUE_y,  162,  348 
panel  data  types 
Panel,  327 

Panel_attribute,  327 
Panel_iteni,  327 
Panel_set.ting,  327 
panel  functions  and  macros,  353 

panel_accept_key  ( > ,  191,  353 
panel_accept_menu  () ,  191,  353 
panel_accept_preview  (} ,  191, 353 
panel_advance_caret  () ,  180,  353 
panel_backup_caret  ( ) ,  180,  353 


panel  functions  and  macros,  continued 

panel_begin_preview  0 , 191, 353 
panel_button_iinage  () ,  168,  353 
panel_cancel__preview  0 , 191,  353 
panel_create_item  ( ) ,  41, 160, 353 
panel_default_handle_event  (} ,  190, 354 
panel_destroy_item  0 , 164,  354 
panel_each_item  ( ) ,  354 
panel_event  () ,  194, 354 
panel_get  ( ) ,  163, 354 
panel_get_value ( ) ,  164 
panel_paint  () ,  185, 354 
panel_set  () ,  162, 354 
panel_set_value  () ,  162 
panel_text_notif y  ( ) ,  181,  354 
panel_update_preview  0 , 191;  355 
panel_update_scrolling_size  ( ) ,  165, 355 
panel_window_event  () ,  194, 355 
panel  item 

accepting  selection,  189 
basic  item  types,  158 
button  item,  158, 167  //wk  169 
choice  item,  158, 170  thru  176 
choice  item  “creep”,  161 
creation,  160 

cycle  item  description,  174 
default  positioning,  161 
destroying,  164 
explicit  positioning,  160 
item  types  for  creation  routine,  160 
layout  of  components,  162 
message  item,  158, 167 
modifying  attributes,  162 
painting,  185 
positioning,  160 
previewing  selection,  189 
retrieving  attributes,  163 
slider  item,  159, 184  thru  185 
table  of  choice  and  toggle  item  attributes,  349 
table  of  slid^  item  attributes,  351 
table  of  text  item  attributes,  352 
text  item,  159, 178  thru  183 
toggle  item,  159, 176  thru  178 
Panel_attribute,  327 
PANEL_EVENT_CANCEL,  190 
PANEL_EVENT_DRAG_IN,  190 
PANEL_EVENT_MOVE_IN,  190 
PANEL_INSERT,  181 
Panel_iteiin,  327 
PANEL_NEXT,  181 
PANEL_NONE,  181 
PANEL_PREVIOUS,  181 
Panel_setting,  327 

performance  hints  —  locking  and  batching,  108 

perror(3),  305 

pipes,  290 

pixels,  103 

pixrect,  103 

pixwin,  101 

background  color,  115 
batching,  109, 110 
biplane  control,  120 
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pixwin,  continued 

cgf  our  frame  buffer,  124 
changing  region  size,  112 
clipping  in  a  pixwin,  1 12 
clipping  with  regions,  112 
colormap,  118 
colormap  manipulation,  113 
colormap  name,  117 
destruction,  113 
determining  region  size,  112 
foregroundcolor,  115 
interface  summary,  356 
inverting  colors,  119 
locking,  108, 109 

locking  and  batching  interaction,  1 12 

performance  hints,  109, 110 

plane  groiqjs,  124 

positioning,  52 

rasterop  function,  104 

regions,  112 

rendering  speed,  108 

retained  regions,  112 

table  of  color  manipulation  functions,  360 

table  of  drawing  functions,  356 

what  is  a  pixwin?,  103 

write  routines,  104 

writing  text,  106 

pixwin  functions  and  macros,  356 

pw_use_fast_monochroine  () ,  125 
pw_batch 0 ,  111 
pw_batch_of  f  () ,  111,  356 
pw_batch_on  {) ,  111,  356 
pw_batchrop  () ,  106, 356 
pw_blackonwhite  () ,  119, 360 
pw_char  ( } ,  105, 356 
pw_close  0,113, 356 
pw__copy  ( ) ,  108, 356 
pw_cyclecolormap  () ,  118,  360 
pw_dbl_access  () ,  123,  360 
pw_dbl_flip  0 , 123, 3^ 
pw_dbl_get  ( ) ,  124, 360 
pw_dbl_release  ( ) ,  123, 360 
pw_dbl_set  ( ) ,  124,  360 
pw_get:  ( ) ,  108,  356 
pw_get_region_rect  () ,  112, 356 
pw_getattributes  () ,  120, 360 
pw_getcmsname  (),  117,  360 
pw_getcolormap  0,118,  360 
pw_getdef  aultcms  ( ) ,  361 
pw_line  0 , 107, 357 
pw_lock  0 , 109, 357 
PW_OP_COUNT,  111 
pw_pf  sysclose  () ,  106, 357 
pw_pf  sysopen  () ,  106, 357 
pw_polygon_2  ( ) ,  107, 357 
pw_polyline  () ,  107, 357 
pw_polypoint  () ,  105, 357 
pw_put  ( ) ,  104,  357 
pw_put attributes  {) ,  120,  361 
pw_put colormap  0, 118, 121,  361 
pw_read  ( ) ,  108, 358 
pw_region  () ,  112, 358 
pw_replrop  ( ) ,  105, 358 
pw_reset  ( ) ,  110, 358 


pixwin  functions  and  macros,  continued 
pw_reversevideo  () ,  119,  361 
pw_rop  ( ) ,  104, 358 
pw_set_region_rect  () ,  112, 358 
pw_setcmsname  () ,  117,  361 
pw_show  0 ,  111,  358 
pw_stencil  () ,  106,  358 
pw_text  0 , 106, 359 
pw_traprop  ( ) ,  107,  359 
pw_ttext  { ) ,  106, 359 
pw_unlock  0 , 109,  359 
pw_vector  () ,  105,  359 
pw_whiteonblack  ( > ,  119, 361 
pw_write  () ,  104,  359 
pw_writebackground  0 , 104, 359 
text  routines,  105 
polling,  295 

pop-up  windows,  16, 44  thru  49 
blocking,  47 
example  program,  389 
non-blocking,  46 
restrictions,  49 

porting  programs  to  SunView,  303 

SimWindows-based,  477,  see  converting  programs  to  Sun- 
View 

programmatic  scrolling,  275 
pty  (pseudo-tty),  57 
pw_bat  ch,  1 1 1 , 356 

R 

reading  events,  97 
Rect  struct,  52 

refusing  the  keyboard  input  focus,  88 
regions  of  a  pixwin,  1 12 

registering  an  event  handler  with  the  Notifier,  288 
releasing  the  event  lock,  97 
rendering  speed,  108 
reserved  namespaces,  30 

restrictions  on  use  of  UNIX  facilities  by  SunView  applications,  285 
row/column  space  in  a  window,  53 
example  program,  406 

s 

sample  programs,  see  example  programs 
Scroll_motion,  327 
scrollbar,  267, 327 
basic  usage,  272 
model,  269 

programmatic  scrolling,  275 
SCROLLBAR  default  symbol,  272 
table  of  attributes,  362 
table  of  functions,  365 
thumbing,  271 
use  with  canvases,  64 
use  with  panels,  165 
user  interface,  271 
scrollbar  attributes,  362 

SCROLL_ABSOLUTE_CURSOR,  362 
SCROLL_ACTIVE_CDRSOR,  362 
SCROLL_ADVANCED_MODE,  362 
SCROLL_BACKWARD_CURSOR,  362 
SCROLL  BAR  COLOR,  362 
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scrollbar  attributes,  continued 

SCROLL_BAR_DISPLAY_LEVEL.  362 
SCROLL_BORDER,  362 
SCROLL_BOBBLE_COLOR,  362 
SCROLL_BaBBLE_DISPLAY_LEVEL,  362 
SCROLL_BUBBLE_MARGIN,  362 
SCROLL_DIRECTION,  273,  362 
SCROLL_END_POINT_AREA,  362 
SCROLL_FORWARD_CORSOR,  362 
SCROLL_GAP,  362 
SCROLL_HEIGHT,  272,  363 
SCROLL_LAST_VIEW_START,  275, 363 
SCROLL_LEFT,  363 
SCROLL_LINE_HEIGHT,  363 
SCROLL_MARGIN,  363 
SCROLL_MARK,  363 
SCROLL_NORMALIZE,  363 
SCROLL_NOTIFY_CLIENT,  363 
SCROLL_OBJECT,  363 
SCROLL__OB  JECT_LENGTH,  269,  363 
SCROLL_PAGE_BUTTON_LENGTH,  363 
SCROLL_PAGE_BUTTONS,  363 
SCROLL_PAINT_BUTTONS_PROC,  363 
SCROLL_PIXWIN,  363 
SCROLL__PLACEMENT,  272,  363 
SCROLL_RECT,  272,  363 
SCROLL_REPEAT_TIME,  364 
SCROLL_REQUEST_MOTION,  364 
SCROLL_REQUEST_OFFSET,  364 
SCROLL_THICKNESS,  272,  273,  364 
SCROLL_TO_GRID,  364 
SCROLL_TOP,  364 
SCROLL_VIEW_LENGTH,  269,  364 
SCROLL_VIEW_START,  269, 275, 364 
SCROLL_WIDTH,  272, 364 
scrollbar  data  types 

Scroll_motion,  327 
Scrollbar,  327 
Scrollbar_attribute,  327 
Scrollbar_attribute_value,  327 
Scrollbar_setting,  327 
scrollbar  functions,  365 

scrollbar_clear_bubble () ,  365 
scrollbar_create  ( ) ,  165, 272, 365 
scrollbar_destroy  () ,  272 
scrollbar_get  { ) ,  272 
scrollbar_paint  () , 365 
scrollbar_paint_bubble  () ,  365 
scrollbar_|>aint_clear  {) ,  365 
scrollbar_scroll_to  () ,  275,  365 
scrollbar_set  () ,  272,  365 
Scrollbar_attribute,  327 
Scrollbar_attribute_value,  327 
Scrollbar_setting,  327 
selection  of  panel  items 
buttons,  167 
choices,  172 
sliders,  184 
text,  179 
toggles,  176 
Selection  Service,  279 
setting  position  of  mouse  cursor,  91 
Setting  the  contents  of  a  Text  Subwindow 


Setting  the  contents  of  a  Text  Subwindow,  continued 
Setting  contents,  140 
SHIFT_CAPSLOCK,  89 
SHIFT_CTRL,  89 
SHIFT_LEFT,  89 
SHIFT_LOCK,  89 
SHIFT_META,  89 
SHIFT_RIGHT,  89 
SHIFTMASK,  96, 97 
showcolor,  116 
SIGALRM,  286 
sigblock(2),  293 
SIGCHLD,  286 
SIGCONT,  285 
SIGIO,  286 
signal(3),  285, 291 

Notifier-compatible  version,  291 
signals  —  use  with  Notifier,  291 
SIGPIPE,292 
SIGTERM,  286 
SIGURG,  88,  286 
sigvec(2),  285 
SIGVTALRM,  286 
slid^  panel  item,  159,  184  thru  185 
stop  key,  88 
subframe,  16 
subwindow  layout 

discussion  of  image_browser_l  program,  50 
example  program,  401 
subwindows,  16 

changing  layout  dynamically,  52 
definition  of,  19 
specifying  layout,  51,  52 
specifying  size,  50 
<suntool /canvas . h>,  61 
<suntool/icon  .h>,  261 
<suntool/menu  .h>,  221 
<suntool /panel  .h>,  153 
<suntool /scrollbar.  h>,  165,267 
<suntool/seln  .h>,  279 
<suntool  / sunview .  h>,  27 
<suntool/textsw.h>,  129 
<suntool/tty  .h>,  211 
SunView 

changes  in  SunOS  releases,  4 

code  no  longer  supported,  5 

converting  programs  from  SunWindows,  477 

data  types,  324 

file  descriptor  limits,  57 

frame  header,  18 

graphics  standards  in  windows,  3 

history,  4 

interface  outline,  27 
interface  summary,  315 
libraries,  27 
model,  9 
objects,  9 
overview,  3 
plane  groups,  126 
porting  programs  to,  303 
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reserved  namespaces,  30 

restrictions  on  use  of  UNIX  facilities  by  applications,  285 
source  code  of  programs,  389 
standard  functions  for  objects,  29 
summary  of  object  types,  11 
<sunwindow/cins_mono  .h>,  115 
<sunwindow/rect  .h>,  52 
<sunwindow/win_cursor.h>,  253 
SimWindows 

converting  programs  to  SunViev/,  477 
equivalent  code  in  SrmView,  Table  C-1 
syst.ein(3),  286 

system  calls  not  to  be  used  under  SimView,  285 

T 

terminal  emulator  subwindow  —  see  “tty  subwindow”,  211 
text  notification  procedure 
default,  181 

possible  return  values,  181 
text  panel  item,  159, 178  thru  183 
text  subwindow,  129 

as  a  sequence  of  characters,  132 

attribute  ordering,  132 

checking  its  status,  133 

concqjts,  132 

creation,  132 

discarding  edits,  139 

edit  log,  138 

editing  contents  of,  136 

and  the  file  system,  138 

finding  text,  144 

getting  a  text  selection,  132 

insertion  point,  132, 135, 136, 137 

interface  summary,  366 

manipulating  the  backing  store,  136 

marking  text,  145 

matching  a  span  of  characters,  144 

matching  a  specific  pattern,  144 

multiple  views,  147 

notification,  148 

overflow  of  edit  log,  138 

positioning  the  caret,  135 

positioning  the  text,  141 

reading  from,  135 

saving  edits,  139 

setting  selection,  147 

storing  edits,  139 

table  of  attributes,  366 

table  of  functions,  372 

table  of  Text  sw_act  ion  attributes,  149,  370 
table  of  Textsw_status  values,  134,  371 
vwiting  to,  134 

text  subwindow  attributes,  366 

TEXTSW_ADJUST_IS_PENDING_DELETE,  366 
TEXTSW^AGAIN_RECORDING,  366 
TEXTSW_AUTO_INDENT,  366 
TEXTSW_AUTO_SCROLL_BY,  366 
TEXTSW_BLINK_CARET,  366 
TEXTSW^BROWSING,  366 
TEXTSW__CHECKPOINT_FREQUENCY,  366 
TEXTSW^CLIENT_DATA,  366 
TEXTSW  CONFIRM  OVERWRITE,  366 


text  subwindow  attributes,  continued 

TEXTSW_CONTENTS,  135, 139,  366 
TEXTSW_CONTROL_CHARS_USE_FONT,  366 
TEXTSW_DISABLE_CD,  366 
TEXTSW_DISABLE__LOAD,  367 
TEXTSW_EDIT_COUNT,  367 
TEXTSW_FILE,  46, 133, 367 
TEXTSW_FILE_CONTENTS,  367 
TEXTSW_FIRST,  133, 142,  367 
TEXTSW_FIRST_LINE,  142,  367 
TEXTSW_HISTORY_LIMIT,  367 
TEXTSW_IGNORE_LIMIT,  367 
TEXTSW_INSERT_FROM_FILE,  367 
TEXTSW_INSERT_MAKES_VISIBLE,  367 
TEXTSW_INSERTION_POINT,  135,  367 
TEXTSW_LEFT_MARGIN,  367 
TEXTSW_LENGTH,  132, 367 
TEXTSW_LINE_BREAK_ACTION,  367 
TEXTSW_LOWER_CONTEXT,  367 
TEXTSW_MARK_DEFAOLTS,  145 
TEXTSW_MARK_MOVE_AT_INSERT,  145 
TEXTSW_MEMORY_MAXIMUM,  138, 368 
TEXTSW_MENU,  368 
TEXTSW_MODIFIED,  133,  368 
TEXTSW_MULTI_CLICK_SPACE,  368 
TEXTSW_MULTI_CLICK_TIMEOUT,  368 
TEXTSW_NOTIFY_PROC,  148,  368 
TEXTSW_READ_ONLY,  368 
TEXTSW_SCROLLBAR,  368 
TEXTSW_STATUS,  132, 133, 368 
TEXTSW_STORE_CHANGES_FILE,  368 
TEXTSW_STORE_SELF_IS_SAVE,  368 
TEXTSW_UPDATE_SCROLLBAR,  369 
TEXTSW_UPPER_CONTEXT,  369 
text  subwindow  constants 

TEXTSW__INFINITY,  135,  136,  137 
TEXTSW_UNIT_IS_CHAR,  136 
TEXTSW_UNIT_IS_LINE,  136 
text  subwindo  w  data  types 
Textsw,  327 
Textsw_index,  132,  327 
Textsw_status,  133,327 
text  subwindow  functions,  372 

textsw_add_mark  () ,  145,  372 
textsw_append_f  ile_name  () ,  138,  372 
textsw_delete  () ,  136,  372 
textsw_edit  () ,  136, 372 
textsw_erase  ( ) ,  136,  372 
textsw_file_lines_visible  () ,  143,  372 
textsw_f  ind_bytes  ( ) ,  144, 372 
textsw_f ind_mark  () ,  146, 373 
textsw_first  (),  147,373 
textsw_index_for_f  ile_line  () ,  142,  373 
textsw_insert  {),  134,373 
textsw_match_bytes  () ,  144,  373 
textsw_next  () ,  147, 373 
textsw_normalize_view  () ,  143,  373 
textsw_possibly_normalize  () ,  143,  373 
textsw_remove_inark  () ,  146,  374 
textsw_replace_bytes  () ,  137,  374 
textsw_reset  (),  139, 150,  374 
textsw_save  {) ,  139, 150, 374 
textsw_screen_line_count  () ,  143, 374 
textsw  scroll  lines  () ,  142, 374 
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text  subwindow  functions,  continued 

text sw_set_select ion  () ,  147, 374 
textsw_store  (),  150 
textsw_store_f  ile  () ,  139,  375 
Text  sw,  327 
Text  sw_act  ion,  148 
Text  sw_act ion  attributes,  370,  149 

TEXTSW_ACTION_CAPS_LOCK,  149,  370 
TEXTSW_ACTION_CHANGED_DIRECTORY,  149,  370 
TEXTSW_ACTION_EDITED_FILE,  149,  370 
TEXTSW_ACTION_FILE_IS_READONLY,  149,  370 
TEXTSW_ACTION_LOADED_FILE,  149,  370 
TEXTSW_ACTION_EDITED_FILE,  150 
TEXTSW_ACTION_LOADED_FILE,  150 
TEXTSW_ACTION_TOOL_CLOSE,  149,  370 
TEXTSW_ACTION_TOOL_DESTROY,  149,  370 
TEXTSW_ACTION_TOOL_MGR,  149, 370 
TEXTSW_ACTION_TOOL_QUIT,  149,  370 
TEXTSW_ACTION_USING_MEMORY,  149,  370 
Text  sw_index,  132,  327 
TEXTSW_INFINITY,  135,  136,  137 
Textsw_status,  133,  327 
Text  sw_status  values,  371,  134 

TEXTSW_STATUS_BAD_ATTR,  134,  371 
TEXTSW_STATOS_BAD_ATTR_VALUE,  134,  371 
TEXTSW_STATUS_CANNOT_ALLOCATE,  134,  371 
TEXTSW_STATUS_CANNOT_INSERT_FROM_FILE,  134, 
371 

TEXTSW_STATUS_CANNOT_OPEN_INPDT,  134,  371 
TEXTSW_STATUS_OKAY,  134,  371 
TEXTSW_STATUS_OTHER_ERROR,  134,  371 
TEXTSW_STATUS_OUT_OF_MEMORY,  134,  371 
TEXTSW_UNIT_IS_CHAR,  136 
TEXTSW_UNIT_IS_LINE,  136 
timeout  events,  294 
toggle  panel  item,  159,  176  thru  178 

translating  events  from  canvas  space  to  window  space,  70, 98 
translating  events  from  panel  space  to  window  space,  193 
tty  subwindow 
creating,  213 

differences  with  Sun  console,  214 
example  program,  412 
example  program  to  list  files,  42 
file  descriptor,  215 
input/ou^ut  to  tty  subwindow,  213 
interface  summary,  376 
monitoring,  215 
overview,  21 1 
reading  and  writing,  215 
special  escape  sequences,  215 
standard  escape  sequences,  214 
table  of  functions,  376 
table  of  special  escape  sequences,  377 
tty  subwindow  attributes 

TTY_ARGV,  213, 215, 216, 376 
TTY_CONSOLE,  376 
TTY_PAGE_MODE,  376 
TTY_QDIT_ON_CHILD_DEATH,  376 
tty  subwindow  fimctions,  376 
example  program,  412 
ttysw_input  0,42,  213,  376 
tty  sw_output.  ( ) ,  214, 376 
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UNIX  system  calls  and  SunView 
alarm(3),  285 
f  cntl(2),  286,  290 
f  ree(3),  311 
g6titimer(2),  285 
I/O  in  a  tty  subwindow,  215 
ioctl(2),  286 
perror(3),  305 
sigblock(2),  293 
signal(3),  285, 291 
sigvec(2),  285 
system  calls  not  to  be  used,  285 
wait(2),  286 
wait3(2),  285, 288 

V 

views  in  text  subwindows,  147 
Virtual  User  Input  Device  (VUID),  80 

w 

wait(2),  286 
wait3(2),  285, 288 
WIN_ASCII_EVENTS,  90,  333 
WIN_EXTEND_TO_EDGE,  50,  51 
WIN_IN_TRANSIT_EVENTS,  90,  333 
WIN_LEFT_KEYS,  90,  333 
WIN_MOUSE_  BUTTONS,  90,  333 
WIN_NO_EVENTS,  90,  333 
WIN_REPAINT,  87 
WIN_RESIZE,  87 
WIN_RIGHT_KEYS,  90,  333 
WIN_STOP,  88 
WIN_TOP_KEYS,  90,  333 
WIN_UP_ASCII_EVENTS,  90,  333 
WIN_UP_EVENTS,  90,  333 
window,  33 

classes  of  windows,  16 
creation,  35 
destruction,  36 

initiating  event  processing,  35 
interface  summary,  379 
limit  to  number  of  windows,  57 
simplest  SunView  program,  37 
table  of  attributes,  379 
table  of  functions  and  macros,  384 
table  of  input-related  window  attributes,  334 
window  attributes,  379 
WIN_BELOW,  379 
WIN_BOTTOM_MARGIN,  53,  379 
WIN_CLIENT_DATA,  379 
WIN_COLUMN_GAP,  53,  379 
WIN_COLUMN_WIDTH,  53,  379 
WIN_COLUMNS,  50,  159,  379 
WIN_CONSUME_KBD_EVENT,  70,  379 
WIN_CONSUME_KBD_EVENTS,  379 
WIN_CONSUME_PICK_EVENT,  379 
WIN_CONSUME_PICK_EVENTS,  379 
WIN_CDRSOR,  255,  256,  379 
WIN__DEVICE_NAME,  379 
WIN_DEVICE_NUMBER,  379 
WIN  ERROR  MSG,  40,  379 
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window  attributes,  continued 

WIN_EVENT_PROC,  70,  81,  379 
WIN_EVENT_STATE,  96,  379 
WIN_FD,  379 

WIN_FIT_HEIGHT,  41,  379 
WIN_FIT_WIDTH,  41,  380 
WIN_FONT,  41, 160,  309,  380 
WIN_GRAB_ALL_INPUT,  92,  380 
WIN_HEIGHT,  159,  380 

WIN_HORIZONTAL_SCROLLBAR,  165,  267,  380 
WIN_lGNORE_KBD_EVENT,  380 
WIN_IGNORE_KBD_EVENTS,  380 
WIN_IGNORE_PICK_EVENT,  380 
WIN_IGNORE_PICK_EVENTS,  380 
WIN_INPUT_DESIGNEE,  92,  380 
WIN_KBD_FOCUS,  380 
WIN_KBD_INPDT_MASK,  380 
WIN_KEYBOARD_FOCUS,  91 
WIN_LEFT_MARGIN,  53,  380 
WIN_MENU,  380 
WIN_MOUSE_XY,  91,  380 
WIN_NAME,  380 
WIN_OWNER,  380 
WIN_PERCENT_HEIGHT,  380 
WIN_PERCENT_WIDTH,  381 
WIN_PICK_INPUT_MASK,  381 
WIN_PIXWIN,  65,  103,  381 
WIN_RECT,  52,  381 
WIN_RIGHT_MARGIN,  53,  381 
WIN_RIGHT_OF,  381 
WIN_ROW_GAP,  53, 381 
WIN_ROW_HEIGHT,  53,  381 
WIN_ROWS,  50,  159,  381 
WIN_SCREEN_RECT,  381 
WIN_SHOW,  46,  381 
WIN_TOP_MARGIN,  53,  381 
WIN_TYPE,  381 

WIN_VERTICAL_SCROLLBAR,  165, 267,  381 
WIN_WIDTH,  159,381 
WIN_X,  52,  381 
WIN_Y,  52,  381 

window  classes 
base  frame,  16 
frame,  16 
pop-up,  16 
subframe,  16 
subwindow,  16 

window  functions  and  macros,  384 
window_bell  ( } ,  384 
window_create  ( ) ,  35,  63,  297,  384 
window_default_event_j5roc  () ,  81,  384 
window_destroy  ( ) ,  36, 384 
window_done  ( ) ,  36,  384 
window_f  it  ( } ,  384 
window_fit_height  (} ,  41, 
window_fit_width  0 , 41,  384 
window_get  ( ) ,  35, 384 
window_loop  () ,  48,  385 
window_main_loop  ( ) ,  35,  303,  385 
window_read_event  () ,  71,  97,  193,  385 
window_refuse_kbd_focus  {) ,  88,  385 
window_release_event_lock  () ,  97,  385 
window_return  ( ) ,  48,  385 
window_set  ( ) ,  35,  162, 385 
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